agentic-graph-mem 1.9.4
Production-Grade Agent Memory Framework for Agentic AI
License: MIT
Requires Python: >=3.9
Keywords: agent, agentic-ai, ai, embedding, graphrag, knowledge-graph, llm, memory, neo4j, rag

# 🧠 GraphMem

## **The Human Brain for Your AI Agents**

[![PyPI](https://img.shields.io/pypi/v/agentic-graph-mem.svg)](https://pypi.org/project/agentic-graph-mem/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/badge/github-Al--aminI/GraphMem-blue.svg)](https://github.com/Al-aminI/GraphMem)

> **"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.**

---

## 🧬 Why GraphMem Changes Everything

### The Problem with Current AI Memory

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.

### The GraphMem Solution: Memory That Thinks

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" |

---

## 🚀 Revolutionary Features

### 1. 🕰️ Point-in-Time Memory (Temporal Validity)

**"Who was CEO in 2015?"** — No other memory system can answer this.

```python
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?"

### 2. ⭐ PageRank Centrality (Hub Detection)

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).

```python
# 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 location
```

### 3. 🧠 Self-Evolution (Like Human Memory)

```python
memory.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**.

### 4. 🏢 Enterprise Multi-Tenant Isolation

**Each user gets their own brain.** Complete data separation.

```python
# 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:*       │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## 💡 The 3-Line API

```python
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
```

---

## 🏗️ Architecture

### High-Level Overview

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                                  🧠 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   │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
```

### Data Flow: Ingest → Query → Evolve

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              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      │     │ • Cac