Skip to content

Quick Start

Get GraphMem running in 5 minutes.

Step 1: Install

pip install agentic-graph-mem

For persistent storage (recommended): 

pip install "agentic-graph-mem[libsql]"

Step 2: Configure

Important: Enable Persistence!

By default, GraphMem uses in-memory storage (data is lost on restart). Add turso_db_path to persist your data!

from graphmem import GraphMem, MemoryConfig

config = MemoryConfig(
    # LLM for extraction and querying
    llm_provider="openai",
    llm_api_key="sk-...",
    llm_model="gpt-4o-mini",

    # Embeddings for semantic search
    embedding_provider="openai",
    embedding_api_key="sk-...",
    embedding_model="text-embedding-3-small",

    # ✅ PERSISTENCE: Data survives restarts!
    turso_db_path="my_agent_memory.db",
)

memory = GraphMem(config)

from graphmem import GraphMem, MemoryConfig

config = MemoryConfig(
    # LLM for extraction and querying
    llm_provider="openai",
    llm_api_key="sk-...",
    llm_model="gpt-4o-mini",

    # Embeddings for semantic search
    embedding_provider="openai",
    embedding_api_key="sk-...",
    embedding_model="text-embedding-3-small",
    # ⚠️ No turso_db_path = data lost on restart!
)

memory = GraphMem(config)

Step 3: Learn (Ingest)

# Feed information to memory
memory.ingest("""
    Tesla, Inc. is an American electric vehicle company.
    Elon Musk is the CEO. Founded in 2003, Tesla's mission
    is to accelerate the transition to sustainable energy.
""")

memory.ingest("""
    SpaceX is led by Elon Musk as CEO. Founded in 2002,
    SpaceX designs rockets. Goal: make humanity multiplanetary.
""")

Step 4: Recall (Query)

# Ask questions
response = memory.query("Who is the CEO of Tesla?")
print(response.answer)  # "Elon Musk"

response = memory.query("What companies does Elon Musk lead?")
print(response.answer)  # "Tesla and SpaceX"

Step 5: Evolve

# Let memory mature (consolidate, decay, improve)
memory.evolve()

Complete Example

from graphmem import GraphMem, MemoryConfig

# Configure with persistence
config = MemoryConfig(
    llm_provider="openai",
    llm_api_key="sk-...",
    llm_model="gpt-4o-mini",
    embedding_provider="openai",
    embedding_api_key="sk-...",
    embedding_model="text-embedding-3-small",

    # ✅ Enable persistence (REQUIRED for production!)
    turso_db_path="my_agent_memory.db",
)

# Initialize with consistent memory_id AND user_id to find your data again
memory = GraphMem(config, memory_id="my_agent", user_id="default")

# Learn
memory.ingest("Tesla is led by CEO Elon Musk. Founded in 2003.")
memory.ingest("SpaceX, founded by Elon Musk in 2002, builds rockets.")
memory.ingest("Neuralink develops brain-computer interfaces.")

# Recall
response = memory.query("What companies does Elon Musk lead?")
print(response.answer)
# → "Elon Musk leads Tesla, SpaceX, and Neuralink."

print(f"Confidence: {response.confidence}")
# → 0.95

# Evolve
events = memory.evolve()
for event in events:
    print(f"{event.evolution_type}: {event.description}")

# Close when done (ensures data is synced)
memory.close()

REQUIRED: Provide memory_id AND user_id for Persistence

Both parameters are required for data to persist correctly:

# ✅ CORRECT: Both provided - data persists!
memory = GraphMem(config, memory_id="my_agent", user_id="user1")
memory.ingest("...")

# Later session - same IDs load your data!
memory = GraphMem(config, memory_id="my_agent", user_id="user1")
response = memory.query("...")  # Finds your previously ingested data

# ❌ WRONG: No memory_id - new UUID each time, data lost!
memory = GraphMem(config)  # Won't find your old data

# ❌ WRONG: Different user_id - won't see data from other users
memory = GraphMem(config, memory_id="my_agent", user_id="user2")  # Different user

Why both? - memory_id: Identifies the memory session/context (like "chat_1", "agent_memory") - user_id: Isolates data per user/tenant (defaults to "default" if not provided)

For single-user apps, you can use: 

memory = GraphMem(config, memory_id="my_agent", user_id="default")

Using Alternative Providers

config = MemoryConfig(
    llm_provider="azure_openai",
    llm_api_key="your-azure-key",
    llm_api_base="https://your-resource.openai.azure.com/",
    azure_deployment="gpt-4",
    llm_model="gpt-4",
    azure_api_version="2024-02-15-preview",

    embedding_provider="azure_openai",
    embedding_api_key="your-azure-key",
    embedding_api_base="https://your-resource.openai.azure.com/",
    azure_embedding_deployment="text-embedding-ada-002",
    embedding_model="text-embedding-ada-002",

    # ✅ Don't forget persistence!
    turso_db_path="my_agent_memory.db",
)

config = MemoryConfig(
    llm_provider="openai_compatible",
    llm_api_key="sk-or-v1-...",
    llm_api_base="https://openrouter.ai/api/v1",
    llm_model="google/gemini-2.0-flash-001",

    embedding_provider="openai_compatible",
    embedding_api_key="sk-or-v1-...",
    embedding_api_base="https://openrouter.ai/api/v1",
    embedding_model="openai/text-embedding-3-small",

    # ✅ Don't forget persistence!
    turso_db_path="my_agent_memory.db",
)

config = MemoryConfig(
    llm_provider="openai_compatible",
    llm_api_key="not-needed",
    llm_api_base="http://localhost:11434/v1",
    llm_model="llama3.2",

    embedding_provider="openai_compatible",
    embedding_api_key="not-needed",
    embedding_api_base="http://localhost:11434/v1",
    embedding_model="nomic-embed-text",

    # ✅ Don't forget persistence!
    turso_db_path="my_agent_memory.db",
)

config = MemoryConfig(
    llm_provider="anthropic",
    llm_api_key="sk-ant-...",
    llm_model="claude-3-5-sonnet-20241022",

    embedding_provider="openai",
    embedding_api_key="sk-...",
    embedding_model="text-embedding-3-small",

    # ✅ Don't forget persistence!
    turso_db_path="my_agent_memory.db",
)

Adding Cloud Sync (Optional)

For backup and multi-device sync, add Turso Cloud credentials:

config = MemoryConfig(
    # ... LLM config ...

    # Local persistence (REQUIRED)
    turso_db_path="my_agent_memory.db",

    # Cloud sync (OPTIONAL - for backup & multi-device)
    turso_url="libsql://your-db.turso.io",
    turso_auth_token="your-token",
)

How it works

  • turso_db_path creates a local SQLite file (always fast, works offline)
  • turso_url + turso_auth_token enable automatic cloud sync
  • Data is read/written locally first, then synced to cloud

Next Steps