"Memory is the treasury and guardian of all things." β Cicero
GraphMem is the first memory system that thinks like a human brain. It doesn't just store dataβit forgets, consolidates, prioritizes, and evolves exactly like biological memory does.
This is the future of enterprise AI agents.
Every production AI agent faces the same crisis:
Day 1: "Who is the CEO?" β "Elon Musk" β
Day 100: Context window: OVERFLOW π₯
Day 365: "Who is the CEO?" β "John... or was it Jane... maybe Elon?" π€―
Vector databases don't forget. They accumulate garbage until your agent drowns in irrelevant, conflicting, outdated information.
GraphMem implements the four pillars of human memory:
| Human Brain | GraphMem | Why It Matters |
|---|---|---|
| π§ Forgetting Curve | Memory Decay | Irrelevant memories fade naturally |
| π Neural Networks | Knowledge Graph | Relationships between concepts |
| β Importance Weighting | PageRank Centrality | Hub concepts (Elon Musk) > peripheral ones |
| β° Episodic Memory | Temporal Validity | "CEO in 2015" vs "CEO now" |
"Who was CEO in 2015?" β No other memory system can answer this.
from datetime import datetime
from graphmem import GraphMem, MemoryConfig
memory = GraphMem(config)
# GraphMem tracks WHEN facts are true
memory.ingest("John Smith was CEO of ACME from 2010 to 2018")
memory.ingest("Jane Doe became CEO of ACME in July 2018")
# Point-in-time queries - like human episodic memory!
memory.query("Who was CEO in 2015?") # β "John Smith" β
memory.query("Who is CEO now?") # β "Jane Doe" β
memory.query("Who was CEO in 2019?") # β "Jane Doe" β
Use Cases:
- π "What contracts were active last quarter?"
- π "Who was our legal counsel before 2020?"
- π "What was our strategy during COVID?"
GraphMem uses Google's PageRank algorithm to identify important entities:
Importance Formula: Ο(e) = w1Β·f1 + w2Β·f2 + w3Β·f3 + w4Β·f4
where:
f1 = Temporal recency (recent = important)
f2 = Access frequency (used often = important)
f3 = PageRank centrality (well-connected = important) β NEW!
f4 = User feedback (explicit signals)
Result: "Elon Musk" (connected to Tesla, SpaceX, Neuralink) scores 3x higher than "Austin, Texas" (connected only to Tesla HQ).
# PageRank automatically identifies hub entities
Elon Musk: PR = 1.000 ββββββββββββββββββββ # Hub - many connections
Tesla: PR = 0.774 βββββββββββββββ # Important company
Austin: PR = 0.520 ββββββββββ # Just a locationmemory.evolve() # This single line triggers:| Mechanism | What Happens | Human Equivalent |
|---|---|---|
| Decay | Old unused memories fade (importance β 0) | Forgetting curve |
| Consolidation | 5 mentions of "user likes Python" β 1 strong memory | Sleep consolidation |
| Rehydration | Contradictions resolved ("CEO is John" β "CEO is Jane") | Memory updating |
| Importance Scoring | PageRank recalculated | Synaptic strengthening |
Result: 80% memory reduction while keeping what matters.
Each user gets their own brain. Complete data separation.
# Alice's memory
alice = GraphMem(config, user_id="alice", memory_id="chat")
alice.ingest("I work at Google as a senior engineer")
# Bob's memory (COMPLETELY ISOLATED)
bob = GraphMem(config, user_id="bob", memory_id="chat")
bob.ingest("I'm a doctor at Mayo Clinic")
# Alice can NEVER see Bob's data
alice.query("What does Bob do?") # β "No information found" β
# Bob can NEVER see Alice's data
bob.query("Where does Alice work?") # β "No information found" β
Architecture:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Neo4j Global Instance β
ββββββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββ€
β USER: alice β USER: bob β
β βββββββββββββββββββββββββββββββ β βββββββββββββββββββββββββββββββ β
β β π’ Google β π€ Alice β β β π₯ Mayo Clinic β π€ Bob β β
β β β β β β β β β
β β πΌ Senior Engineer β β β π©Ί Doctor β β
β βββββββββββββββββββββββββββββββ β βββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββ€
β Redis Cache (Also Isolated by user_id) β
β alice:query:* alice:search:* β bob:query:* bob:search:* β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
from graphmem import GraphMem, MemoryConfig
# Initialize (works with ANY OpenAI-compatible API)
config = MemoryConfig(
llm_provider="openai_compatible",
llm_api_key="your-key",
llm_api_base="https://openrouter.ai/api/v1",
llm_model="google/gemini-2.0-flash-001",
embedding_provider="openai_compatible",
embedding_api_key="your-key",
embedding_api_base="https://openrouter.ai/api/v1",
embedding_model="openai/text-embedding-3-small",
)
memory = GraphMem(config)
# That's it. 3 methods:
memory.ingest("Tesla is led by CEO Elon Musk...") # β Extract knowledge
memory.query("Who is the CEO?") # β Ask questions
memory.evolve() # β Let memory matureβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π§ GraphMem β
β The Human Brain for AI Agents β
β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β β ingest() β β query() β β evolve() β β
β β Learn new β β Recall + β β Mature β β
β β knowledge β β Reasoning β β memories β β
β ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ β
ββββββββββββΌβββββββββββββββββββββββΌβββββββββββββββββββββββΌβββββββββββββββββββββββββ
β β β
βΌ βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π MULTI-TENANT LAYER β
β β
β Every operation is scoped by: user_id + memory_id β
β β
β βββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββ β
β β USER: alice β β USER: bob β β
β β memory_id: chat_1 β β memory_id: chat_1 β β
β β memory_id: notes β β memory_id: work β β
β β ββββββββββββββββββββ β β ββββββββββββββββββββ β β
β β Complete isolation β
β β Complete isolation β
β β
β βββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β πΈοΈ KNOWLEDGE GRAPH ENGINE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ β
β β ENTITY EXTRACTION β β RELATIONSHIP β β COMMUNITY β β
β β β β DETECTION β β DETECTION β β
β β β’ LLM-powered β β β β β β
β β β’ Named entities β β β’ Semantic links β β β’ Louvain algo β β
β β β’ Type inference β β β’ Temporal bounds β β β’ Auto-clustering β β
β β β’ Descriptions β β β’ [t_s, t_e] β β β’ LLM summaries β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ β
β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ β
β β ENTITY RESOLUTION β β SEMANTIC β β QUERY ENGINE β β
β β β β SEARCH β β β β
β β β’ Alias merging β β β β β’ Multi-hop β β
β β β’ Canonicalizationβ β β’ Vector index β β β’ Cross-cluster β β
β β β’ 95% accuracy β β β’ Cosine sim β β β’ Context assemblyβ β
β β β’ user_id aware β β β’ user_id filter β β β’ LLM synthesis β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π EVOLUTION ENGINE β
β (Human Memory Simulation) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β PAGERANK CENTRALITY β β
β β β β
β β PR(A) = (1-d) + d Γ Ξ£(PR(Ti)/C(Ti)) where d = 0.85 β β
β β β β
β β Hub Detection: β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β Elon Musk ββββββ¬ββββ Tesla ββββ Austin β β β
β β β (HUB) βββββ SpaceX ββββ Hawthorne β β β
β β β PR=1.00 βββββ Neuralink β β β
β β β β β β
β β β PageRank: Elon(1.00) > Tesla(0.77) > SpaceX(0.77) > Austin(0.52)β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββ ββββββββββββββββββββββ β
β β MEMORY DECAY β β CONSOLIDATION β β TEMPORAL VALIDITY β β
β β β β β β β β
β β Ebbinghaus Curve: β β LLM-based merging: β β Time bounds: β β
β β β β β β β β
β β I(t) = IβΒ·e^(-Ξ»t) β β 5 mentions β β β valid_from: t_s β β
β β β β 1 strong memory β β valid_until: t_e β β
β β Ξ» = decay rate β β β β β β
β β β β 80% reduction β β is_valid_at(t) β β
β β Unused β archived β β while keeping value β β supersede(end) β β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββ ββββββββββββββββββββββ β
β β
β Importance Formula: Ο(e) = w1Β·f1 + w2Β·f2 + w3Β·f3 + w4Β·f4 β
β βββ f1: Recency (0.3) - Recent access = important β
β βββ f2: Frequency (0.3) - Used often = important β
β βββ f3: PageRank (0.2) - Well-connected = important (HUB) β
β βββ f4: User signal (0.2) - Explicit importance β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β πΎ STORAGE LAYER β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β CHOOSE YOUR STORAGE BACKEND ββ
β β ββ
β β βββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββ ββ
β β β InMemory β β π₯ TURSO π₯ β β NEO4J β ββ
β β β (Default) β β (Embedded) β β (Enterprise) β ββ
β β βββββββββββββββ€ βββββββββββββββββββ€ βββββββββββββββββββββββ€ ββ
β β β No persist β β SQLite file β β Full graph DB β ββ
β β β Zero config β β Works offline β β ACID + clustering β ββ
β β β Dev/testing β β Cloud sync opt β β Native Cypher β ββ
β β β Python vec β β Native vec π β β HNSW vec π β ββ
β β β β β ~10ms search β β ~5ms search β ββ
β β βββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββ ββ
β β β β β ββ
β β β ALL BACKENDS GET THE SAME FEATURES: β ββ
β β β β
Multi-tenant β
Temporal validity β ββ
β β β β
PageRank β
Memory evolution β ββ
β β β β
Communities β
Entity resolution β ββ
β β βββββββββββββββββββββββ¬ββββββββββββββββββββββββββ ββ
β β β ββ
β βββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββ
β β
β βββββββββββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ β
β β ποΈ NEO4J GRAPH β β β‘ REDIS CACHE β β
β β (Enterprise Option) β β (Optional Layer) β β
β β β β β β
β β βββββββββββββββββββββββββββββββββββ β β ββββββββββββββββββββββββββ β β
β β β ENTITY NODES β β β β EMBEDDING CACHE β β β
β β β β’ id, name, type β β β β β β β
β β β β’ embedding[1536] β β β β Key: emb:{text_hash} β β β
β β β β’ user_id β ISOLATION β β β β TTL: 24 hours β β β
β β β β’ memory_id β β β β 3x faster embeddings β β β
β β β β’ importance, access_count β β β ββββββββββββββββββββββββββ β β
β β βββββββββββββββββββββββββββββββββββ β β β β
β β β β ββββββββββββββββββββββββββ β β
β β βββββββββββββββββββββββββββββββββββ β β β QUERY CACHE β β β
β β β RELATIONSHIP EDGES β β β β (Multi-Tenant!) β β β
β β β β’ valid_from β TEMPORAL β β β β β β β
β β β β’ valid_until β VALIDITY β β β β Key: query:{user}:* β β β
β β β β’ user_id β ISOLATION β β β β TTL: 5 minutes β β β
β β βββββββββββββββββββββββββββββββββββ β β β Instant repeat: 0ms β β β
β β β β ββββββββββββββββββββββββββ β β
β β βββββββββββββββββββββββββββββββββββ β β β β
β β β VECTOR INDEX (HNSW) β β β Auto-Invalidation: β β
β β β Dimension: 1536, cosine β β β β’ ingest() β clear cache β β
β β β ~5ms similarity search β β β β’ evolve() β clear cache β β
β β βββββββββββββββββββββββββββββββββββ β β β’ clear() β clear cache β β
β βββββββββββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ β
β β π₯ TURSO (SQLite) - RECOMMENDED! β β π₯ TURSO CACHE β β
β β (Edge/Offline Option) β β (Built-in to TursoStore) β β
β β β β β β
β β pip install "agentic-graph-mem[libsql]" β ββββββββββββββββββββββββββ β β
β β β β β No Redis needed! β β β
β β β
Persists to local .db file β β β SQLite-based cache β β β
β β β
Works completely offline β β β TTL support β β β
β β β
Optional Turso Cloud sync β β β Multi-tenant keys β β β
β β β
Native F32_BLOB vector search β β β Survives restarts β β β
β β β
~10ms vector similarity β β ββββββββββββββββββββββββββ β β
β β β β β β
β β SAME FEATURES AS NEO4J: β β Great for: β β
β β β’ Temporal validity β
β β β’ Edge AI devices β β
β β β’ PageRank centrality β
β β β’ Offline agents β β
β β β’ Multi-tenant isolation β
β β β’ Mobile apps β β
β β β’ Point-in-time queries β
β β β’ Cost-sensitive deploys β β
β βββββββββββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π€ LLM PROVIDERS β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β OpenAI β β Azure β βAnthropic β β Groq β β Together β β Ollama β β
β β GPT-4o β β OpenAI β β Claude β β Llama β β AI β β Local β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β OpenRouter (100+ Models) β β
β β google/gemini-2.0-flash β anthropic/claude-3.5 β meta-llama/llama-3 β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β INGEST FLOW β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Input Document Knowledge Extraction Storage
ββββββββββββββββ ββββββββββββββββββββ βββββββββββββ
β "Tesla is β βββββββββββΆ β LLM extracts: β βββββββββββΆ β Neo4j OR β
β led by CEO β β β β π₯Turso β
β Elon Musk" β β Entities: β β β
ββββββββββββββββ β β’ Tesla [Org] β β (Tesla)ββββ
β β β’ Elon Musk [Per]β β β β
β β β β βΌ β
β β Relations: β β CEO_OF β
β β β’ (Elon)βCEOββΆ β β β β
β β (Tesla) β β βΌ β
β β β β (Elon) β
β β Temporal: β βββββββββββββ
β β β’ valid_from=now β β
β β β’ valid_until=β β βΌ
β ββββββββββββββββββββ βββββββββββββ
β β β Redis OR β
β β β TursoCacheβ
β βΌ βββββββββββββ
β ββββββββββββββββββββ
β β Entity Resolutionβ
β β β
β β "Elon" = "Musk" β
β β = "Elon Musk" β
β β β Canonical: "Elon Musk"
β ββββββββββββββββββββ
β
ββββ user_id + memory_id tagged on ALL nodes/edges
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β QUERY FLOW β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
User Question Cache Check Retrieval Answer
ββββββββββββββββ βββββββββββββ βββββββββββββ ββββββββββββ
β "Who is the β ββββΆ β Redis β HIT β β ββββΆ β "Elon β
β CEO?" β β Cache β ββββΆ β SKIP! β β Musk" β
β β β β β β β β
β user: alice β β Key: β βββββββββββββ ββββββββββββ
β mem: chat_1 β β query: β
ββββββββββββββββ β alice: β MISS
β β chat_1: β ββββΆ βββββββββββββββββββββββββββββββββ
β β {hash} β β RETRIEVAL β
β βββββββββββββ β β
β β 1. Embed query β
β β 2. Vector search (Neo4j/Turso)β
β β WHERE user_id = 'alice' β
β β AND memory_id = 'chat_1' β
β β 3. Get related edges β
β β 4. Filter by temporal β
β β is_valid_at(now) β
β
β β 5. Rank by importance β
β β (PageRank score) β
β β 6. Build context β
β β 7. LLM generates answer β
β β 8. Cache result in Redis β
β βββββββββββββββββββββββββββββββββ
β
ββββ user_id ensures Alice NEVER sees Bob's data
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EVOLVE FLOW β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Trigger Evolution Cycle Result
ββββββββββββββββ ββββββββββββββββββββββββββββββββββ ββββββββββββββ
β memory β ββββΆ β β β β
β .evolve() β β 1. PAGERANK RECALCULATION β β β’ Hubs β
β β β Build graph from edges β β identifiedβ
β user: alice β β Compute PR scores β β β
β β β Update importance β β β’ 80% β
ββββββββββββββββ β β β memory β
β β 2. MEMORY DECAY β β reduced β
β β I(t) = Iβ Γ e^(-Ξ»t) β β β
β β Archive if I < 0.1 β β β’ Conflictsβ
β β β β resolved β
β β 3. CONSOLIDATION β β β
β β Find similar memories β β β’ Cache β
β β LLM merges duplicates β β cleared β
β β β β β
β β 4. REHYDRATION β ββββββββββββββ
β β Update contradictions β
β β "CEO=John" β "CEO=Jane" β
β β β
β β 5. CACHE INVALIDATION β
β β Clear Redis for user β
β ββββββββββββββββββββββββββββββββββ
β
ββββ Only evolves Alice's data (user_id scoped)
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π MULTI-TENANT ARCHITECTURE β
β (Works identically with Neo4j, Turso, or InMemory) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β STORAGE BACKEND (Neo4j / Turso / InMemory) β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β GLOBAL VECTOR INDEX β β
β β (Entity.embedding, HNSW) β β
β β β β
β β Query: db.index.vector.queryNodes( β β
β β 'entity_embedding_index', β β
β β $top_k * 10, β Fetch extra for filtering β β
β β $query_embedding β β
β β ) β β
β β WHERE node.user_id = $user_id β ISOLATION β β
β β AND node.memory_id = $memory_id β β
β β RETURN node LIMIT $top_k β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββββββ β
β β USER: alice β β USER: bob β β
β β β β β β
β β βββββββββββββββββββββββββββ β β βββββββββββββββββββββββββββββββ β β
β β β memory: chat_1 β β β β memory: chat_1 β β β
β β β βββββββ βββββββ β β β β βββββββ βββββββ β β β
β β β βAliceβββββΆβGoogleβ β β β β β Bob βββββΆβMayo β β β β
β β β βββββββ βββββββ β β β β βββββββ βClinicβ β β β
β β β β β β β β β βββββββ β β β
β β β βΌ β β β β βΌ β β β
β β β ββββββββββ β β β β ββββββββ β β β
β β β βEngineerβ β β β β βDoctorβ β β β
β β β ββββββββββ β β β β ββββββββ β β β
β β βββββββββββββββββββββββββββ β β βββββββββββββββββββββββββββββββ β β
β β β β β β
β β βββββββββββββββββββββββββββ β β βββββββββββββββββββββββββββββββ β β
β β β memory: notes β β β β memory: work β β β
β β β ββββββββ βββββββ β β β β βββββββββ ββββββββ β β β
β β β βPythonββββΆβ ML β β β β β βPatientββββΆβRecordβ β β β
β β β ββββββββ βββββββ β β β β βββββββββ ββββββββ β β β
β β βββββββββββββββββββββββββββ β β βββββββββββββββββββββββββββββββ β β
β β β β β β
β βββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β REDIS CACHE (ISOLATED) β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β β Alice's Keys: Bob's Keys: β β
β β βββββββββββββ ββββββββββ β β
β β query:alice:chat_1:abc123 query:bob:chat_1:xyz789 β β
β β search:alice:chat_1:def456 search:bob:chat_1:uvw321 β β
β β search:alice:notes:ghi789 search:bob:work:rst654 β β
β β β β
β β Shared (same text = same embedding): β β
β β βββββββββββββββββββββββββββββββββββββ β β
β β emb:sha256_of_text β [0.1, 0.2, ...] β β
β β β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β β
Alice can NEVER access Bob's cached queries β
β β
Bob can NEVER access Alice's cached queries β
β β
Embeddings shared (efficiency) - no sensitive data in embeddings β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β° TEMPORAL VALIDITY β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β Every RELATIONSHIP has a time interval: [valid_from, valid_until] β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β CEO TRANSITIONS β β
β β β β
β β Timeline: 2010 2015 2018 2020 2025 β β
β β β β β β β β β
β β βΌ βΌ βΌ βΌ βΌ β β
β β β β
β β John ββCEO_OFβββΆ ACME βββββββββββββββββ β β
β β valid: [2010-01-01, 2018-06-30] β β β
β β β β β
β β Jane ββCEO_OFβββΆ ACME βββββββββββββββββββββββββ β β
β β valid: [2018-07-01, NULL] β NULL = still current β β
β β β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β Point-in-Time Queries: β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β β Q: "Who was CEO in 2015?" β β
β β β β
β β 1. Find edges WHERE relation_type = 'CEO_OF' β β
β β 2. Filter: is_valid_at(datetime(2015, 6, 1)) β β
β β βββ John: valid_from=2010 β€ 2015 β€ valid_until=2018 β
β β
β β βββ Jane: valid_from=2018 > 2015 β β β
β β 3. Return: "John Smith" β β
β β β β
β β Q: "Who is CEO now?" β β
β β β β
β β 1. Filter: is_valid_at(datetime.utcnow()) β β
β β βββ John: valid_until=2018 < now β β β
β β βββ Jane: valid_from=2018 β€ now, valid_until=NULL β
β β
β β 2. Return: "Jane Doe" β β
β β β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β API: β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β β # Check validity at any point in time β β
β β edge.is_valid_at(datetime(2015, 6, 1)) # True/False β β
β β β β
β β # Mark relationship as ended β β
β β edge.supersede(end_time=datetime(2018, 6, 30)) β β
β β β β
β β # Query edges at specific time β β
β β store.query_edges_at_time( β β
β β memory_id="company_kb", β β
β β query_time=datetime(2015, 6, 1), β β
β β relation_type="CEO_OF" β β
β β ) β β
β β β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
graphmem/
βββ core/
β βββ memory.py # GraphMem main class
β βββ memory_types.py # MemoryNode, MemoryEdge (+ temporal validity)
β βββ exceptions.py # Custom exceptions
β
βββ graph/
β βββ knowledge_graph.py # LLM-based extraction
β βββ entity_resolver.py # Deduplication (user_id aware)
β βββ community_detector.py # Topic clustering
β
βββ evolution/
β βββ memory_evolution.py # Evolution orchestrator
β βββ importance_scorer.py # PageRank + multi-factor scoring
β βββ decay.py # Ebbinghaus forgetting curve
β βββ consolidation.py # LLM-based merging (user_id aware)
β βββ rehydration.py # Contradiction resolution
β
βββ retrieval/
β βββ query_engine.py # Multi-hop + cross-cluster
β βββ retriever.py # Context retrieval
β βββ semantic_search.py # Vector search (user_id filtered)
β
βββ stores/
β βββ neo4j_store.py # Graph + temporal + HNSW vector index
β βββ turso_store.py # SQLite + temporal + native vector (NEW!)
β βββ memory_store.py # In-memory (default)
β βββ redis_cache.py # Multi-tenant cache
β
βββ llm/
β βββ providers.py # 10+ LLM providers
β βββ embeddings.py # Embedding + cache
β
βββ context/
βββ context_engine.py # Context assembly
βββ chunker.py # Semantic chunking
βββ multimodal.py # JSON, CSV, Markdown, Code, Web
| Metric | Naive RAG | GraphMem | Advantage |
|---|---|---|---|
| 1K conversations | π₯ Context overflow | β Bounded | Handles growth |
| 10K entities | O(n) = 2.3s | O(1) = 50ms | 46x faster |
| 1 year history | 3,650 entries | ~100 consolidated | 97% reduction |
| Entity conflicts | Duplicates | Auto-resolved | Clean data |
| Temporal queries | β Impossible | β Native | Unique capability |
Naive RAG: Send entire history every query = $$$$$
GraphMem: Retrieve only relevant subgraph = $
βββββ
99% savings
| Requirement | GraphMem |
|---|---|
| Multi-tenant isolation | β
user_id on every node |
| ACID transactions | β Neo4j backend |
| Horizontal scaling | β Neo4j cluster + Redis |
| Audit trail | β Temporal validity history |
| Data sovereignty | β Self-hosted option |
# Core only (in-memory, for development)
pip install agentic-graph-mem
# π₯ RECOMMENDED: Turso (SQLite persistence + offline)
pip install "agentic-graph-mem[libsql]"
# Enterprise: Neo4j + Redis (full graph power)
pip install "agentic-graph-mem[all]"βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β STORAGE BACKEND DECISION TREE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β "Do you need data to persist between restarts?" β
β β β
β ββββββββββββββ΄βββββββββββββ β
β β β β
β NO YES β
β β β β
β βΌ βΌ β
β βββββββββββββββββββ "Do you need complex graph queries β
β β InMemory β (multi-hop traversals, GDS algorithms)?" β
β β β β β
β β β’ Development β ββββββββββββββ΄βββββββββββββ β
β β β’ Testing β β β β
β β β’ Quick POCs β NO YES β
β β β’ Zero config β β β β
β βββββββββββββββββββ βΌ βΌ β
β βββββββββββββββββββ βββββββββββββββββββ β
β β π₯ TURSO β β NEO4J β β
β β β β β β
β β β’ Edge/offline β β β’ Enterprise β β
β β β’ Mobile apps β β β’ Complex graphsβ β
β β β’ Single-user β β β’ Multi-tenant β β
β β β’ No server β β β’ Horizontal β β
β β β’ Simple setup β β scaling β β
β β β’ SQLite-based β β β’ ACID + clusterβ β
β βββββββββββββββββββ βββββββββββββββββββ β
β β β
β "Add high-performance caching?" β
β β β
β βββββββββ΄ββββββββ β
β YES NO β
β β β β
β βΌ βΌ β
β βββββββββββββ βββββββββββββ β
β β + REDIS β β Neo4j onlyβ β
β β Cache β β (still β β
β β β β great!) β β
β βββββββββββββ βββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Feature | InMemory | Turso π₯ | Neo4j |
|---|---|---|---|
| Persistence | β | β SQLite file | β Server |
| Works Offline | β | β | β |
| Vector Search | Python | Native F32_BLOB |
Native HNSW |
| Cloud Sync | β | β Optional | β |
| Setup Complexity | None | One file path | Server required |
| Multi-hop Queries | β NetworkX | β NetworkX | β Native Cypher |
| PageRank | β | β | β |
| Temporal Validity | β | β | β |
| Multi-tenant | β | β | β |
| Best For | Dev/Test | Edge/Offline | Enterprise |
from graphmem import GraphMem, MemoryConfig
config = MemoryConfig(
llm_provider="openai_compatible",
llm_api_key="sk-or-v1-your-key",
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-your-key",
embedding_api_base="https://openrouter.ai/api/v1",
embedding_model="openai/text-embedding-3-small",
)
memory = GraphMem(config)
# 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."
# Mature
memory.evolve() # Consolidates, decays, re-ranks importancefrom graphmem import GraphMem, MemoryConfig
# Turso gives you persistence without running Neo4j!
# Data survives restarts, works offline, can sync to cloud
config = MemoryConfig(
llm_provider="openai_compatible",
llm_api_key="sk-or-v1-your-key",
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-your-key",
embedding_api_base="https://openrouter.ai/api/v1",
embedding_model="openai/text-embedding-3-small",
# π₯ Just add a file path - that's it!
turso_db_path="my_agent_memory.db",
# Optional: Sync to Turso Cloud for backups/multi-device
# turso_url="https://your-db.turso.io",
# turso_auth_token="your-token",
)
memory = GraphMem(config, user_id="alice")
# All data persists in my_agent_memory.db
memory.ingest("Alice is a software engineer at Google.")
memory.save() # Data survives restart!
# Later, in a new session:
memory2 = GraphMem(config, user_id="alice")
response = memory2.query("Where does Alice work?") # Still knows! β
Why Turso over InMemory?
- β Data survives restarts (SQLite file)
- β Works offline (no network needed)
- β Optional cloud sync (Turso Cloud)
- β No server to manage (unlike Neo4j)
- β Per-user database files (true isolation)
from graphmem import GraphMem, MemoryConfig
# Base config (shared across all users)
base_config = MemoryConfig(
llm_provider="openai_compatible",
llm_api_key="sk-or-v1-your-key",
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-your-key",
embedding_api_base="https://openrouter.ai/api/v1",
embedding_model="openai/text-embedding-3-small",
# Production storage
neo4j_uri="neo4j+ssc://xxx.databases.neo4j.io",
neo4j_username="neo4j",
neo4j_password="your-password",
redis_url="redis://default:password@your-redis.cloud.redislabs.com:17983",
)
class ChatService:
def get_memory(self, user_id: str, session_id: str) -> GraphMem:
"""Each user gets isolated memory."""
return GraphMem(
base_config,
user_id=user_id, # β Complete isolation
memory_id=session_id, # β Per-session memory
)
def chat(self, user_id: str, session_id: str, message: str) -> str:
memory = self.get_memory(user_id, session_id)
# Store user message as memory
memory.ingest(message)
# Generate response using memory
response = memory.query(message)
return response.answer
# Usage
service = ChatService()
# Alice's session (isolated)
alice_response = service.chat("alice", "session_1", "I'm a software engineer at Google")
alice_response = service.chat("alice", "session_1", "What do I do?") # β "Software engineer at Google"
# Bob's session (completely separate)
bob_response = service.chat("bob", "session_1", "I'm a doctor")
bob_response = service.chat("bob", "session_1", "What does Alice do?") # β "No information found"from datetime import datetime
from graphmem.core.memory_types import MemoryEdge
from graphmem.stores.neo4j_store import Neo4jStore
store = Neo4jStore(uri, user, password)
# Track CEO transitions
john_ceo = MemoryEdge(
id="john_ceo",
source_id="john_smith",
target_id="acme_corp",
relation_type="CEO_OF",
valid_from=datetime(2010, 1, 1),
valid_until=datetime(2018, 6, 30), # John left
)
jane_ceo = MemoryEdge(
id="jane_ceo",
source_id="jane_doe",
target_id="acme_corp",
relation_type="CEO_OF",
valid_from=datetime(2018, 7, 1),
valid_until=None, # Current CEO
)
# Query by time period
ceo_2015 = store.query_edges_at_time(
memory_id="company_kb",
query_time=datetime(2015, 6, 1),
relation_type="CEO_OF"
)
# β Returns John Smith's edge
ceo_now = store.query_edges_at_time(
memory_id="company_kb",
query_time=datetime.utcnow(),
relation_type="CEO_OF"
)
# β Returns Jane Doe's edge
# Mark relationship as ended
store.supersede_relationship(
memory_id="company_kb",
edge_id="jane_ceo",
end_time=datetime(2025, 12, 31) # Jane leaves
)cd graphmem/evaluation
python run_eval.pyUses MultiHopRAG dataset (2,556 QA samples, 609 documents).
importance(t) = importance_0 Γ e^(-Ξ» Γ (t - last_access))
Just like human memory, unused information fades exponentially.
PR(A) = (1-d) + d Γ Ξ£(PR(Ti)/C(Ti))
Hub entities (connected to many concepts) are more importantβexactly like neural hubs in the brain.
valid(r, t) = 1[t_s(r) β€ t β€ t_e(r)]
Every relationship has a time interval, enabling episodic memory recall.
| Scale | Users | Strategy | Infrastructure |
|---|---|---|---|
| Development | 1 | InMemory (no persistence) | Nothing required |
| Personal/Edge | 1-10 | π₯ Turso (local SQLite) | Single .db file per user |
| Startup | 1-100 | Turso + Cloud sync | Turso Cloud (free tier) |
| Growth | 100-10K | Neo4j + Redis | Neo4j Aura Pro + Redis Cloud |
| Enterprise | 10K-100K | Sharded by region | Neo4j Enterprise Cluster |
| Global | 100K+ | Database per tenant | Multi-region Neo4j Fabric |
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β STORAGE SELECTION GUIDE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β π§ͺ DEVELOPMENT / TESTING β
β βββΆ InMemory (default) β
β β’ pip install agentic-graph-mem β
β β’ config = MemoryConfig(...) # No storage params needed β
β β
β π± EDGE / OFFLINE / SIMPLE APPS β
β βββΆ π₯ Turso (RECOMMENDED) β
β β’ pip install "agentic-graph-mem[libsql]" β
β β’ config = MemoryConfig(..., turso_db_path="agent.db") β
β β’ Works offline, data persists, no server! β
β β
β π’ ENTERPRISE / HIGH-SCALE β
β βββΆ Neo4j + Redis β
β β’ pip install "agentic-graph-mem[all]" β
β β’ config = MemoryConfig(..., neo4j_uri=..., redis_url=...) β
β β’ Complex graph queries, horizontal scaling, ACID β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
# Core (no external services, in-memory only)
pip install agentic-graph-mem
# With Turso (SQLite persistence, offline-first) - SIMPLEST OPTION!
pip install agentic-graph-mem libsql
# With Neo4j persistence (full graph database)
pip install "agentic-graph-mem[neo4j]"
# With Redis caching (high-performance cache)
pip install "agentic-graph-mem[redis]"
# Full production stack (Neo4j + Redis)
pip install "agentic-graph-mem[all]"| Backend | Persistence | Vector Search | Graph Algorithms | Offline | Use Case |
|---|---|---|---|---|---|
| InMemory | β | β (in Python) | β (NetworkX) | β | Development, testing |
| Turso | β | β (native) | β (NetworkX) | β | Edge/offline AI, simple deploys |
| Neo4j | β | β (HNSW) | β (GDS, native) | β | Enterprise, complex graphs |
| Redis | β | β | β | Caching layer only |
GraphMem isn't just another vector database wrapper. It's a paradigm shift:
| Old Way | GraphMem Way |
|---|---|
| Store everything | Remember what matters |
| Static forever | Evolves over time |
| No relationships | Rich knowledge graph |
| "Who is CEO?" | "Who was CEO in 2015?" |
| One user fits all | Enterprise multi-tenant |
| Hope for the best | PageRank prioritization |
The agents of tomorrow will have memories that think.
We're building the future of AI memory. Join us!
- π Report bugs
- π‘ Request features
- π Submit PRs
MIT License - see LICENSE.
- Inspired by cognitive neuroscience research on human memory
- Built on Neo4j, Redis, Turso (libSQL), and OpenAI
- PageRank algorithm by Larry Page and Sergey Brin
- Turso team for the amazing embedded SQLite with vector search
Made with π§ by Al-Amin Ibrahim
"Give your AI agents the memory they deserve."