Memory Graph — Knowledge Graph Plugin

The Problem

AI agents forget everything between sessions. Context windows overflow. MEMORY.md files become unstructured dumps. RAG retrieval misses relationships.

The Solution

agent-memory-graph builds a structured knowledge graph from your conversations — automatically. Every person, project, tool, and relationship is extracted, stored locally in SQLite, and queryable with natural language.

You: "I just met Viktor, the CTO of Nexus Labs. They're building SkyNet-X using Rust."

→ Graph auto-extracts:
  Viktor (Person) ──[CTO_OF]──→ Nexus Labs (Company)
  Nexus Labs ──[BUILDS]──→ SkyNet-X (Project)
  SkyNet-X ──[USES]──→ Rust (Language)

You: "Who works at Nexus Labs?"
→ "People at Nexus Labs: Viktor"

You: "How is Viktor connected to Rust?"
→ "Viktor →[CTO_OF]→ Nexus Labs →[BUILDS]→ SkyNet-X →[USES]→ Rust"

✨ Features

📋 Requirements

• Node.js 18–22 (recommended) — better-sqlite3 has prebuilt binaries
• Node.js 24 — works but requires build tools (gcc, make, python3) for native compilation
• Any OpenAI-compatible LLM — for entity extraction (optional for manual operations)

🚀 Quick Start

npm install agent-memory-graph

As a library

import { MemoryGraph } from 'agent-memory-graph';

const graph = new MemoryGraph();

// Ingest — entities and relationships are auto-extracted
await graph.ingest(
  "Alice is the CTO of TechCorp. She leads the Platform team " +
  "and uses Kubernetes, Go, and PostgreSQL."
);

// Query with natural language
await graph.ask("What does Alice use?");
// → "Alice: USES → Kubernetes, Go, PostgreSQL"

await graph.ask("Who works at TechCorp?");
// → "People at TechCorp: Alice"

// Find hidden connections
graph.findPath("Bob", "PostgreSQL");
// → Bob →[MEMBER_OF]→ Platform team →[LED_BY]→ Alice →[USES]→ PostgreSQL

graph.close();

As a CLI

# Ingest from text
memory-graph ingest "Started learning Rust for the new backend service"

# Ask questions
memory-graph ask "What am I learning?"
# → "Found: Rust (Language)"

# Search entities
memory-graph search "Rust"

# Find paths
memory-graph path "Alice" "PostgreSQL"

# Visualize
memory-graph visualize --format mermaid

# Stats
memory-graph stats
# → Entities: 42 | Relationships: 67 | Types: Person, Tool, Project...

🔌 OpenClaw Plugin (Recommended)

The killer feature: install as an OpenClaw plugin and your agent automatically remembers everything.

Install

openclaw plugins install agent-memory-graph --dangerously-force-unsafe-install
openclaw gateway restart

⚠️ The --dangerously-force-unsafe-install flag is required because the plugin reads environment variables (API keys) and makes network calls (to your LLM provider). This is expected behavior for LLM-powered extraction.

What happens next

1. Every message (>20 chars) is auto-ingested into the knowledge graph
2. 5 tools are registered for the agent to call:
   • memory_graph_ingest — manually add knowledge
   • memory_graph_query — natural language questions
   • memory_graph_search — keyword search
   • memory_graph_path — find connections between entities
   • memory_graph_stats — graph statistics
3. Data persists in ~/.openclaw/data/memory-graph.db — survives /new, /reset, and restarts

Demo: Auto-detect in action

[19:02] You: Hey, I just met Viktor who's the CTO of Nexus Labs.
             They're building SkyNet-X using Rust and ROS2.

        ┌─ memory-graph hook ─────────────────────────────┐
        │ ✓ Auto-ingested: 4 entities, 5 relationships    │
        │   Viktor (Person), Nexus Labs (Company),         │
        │   SkyNet-X (Project), Rust (Language)            │
        └──────────────────────────────────────────────────┘

[19:05] You: Who works at Nexus Labs?

        Agent calls: memory_graph_query("Who works at Nexus Labs?")
        → "People at Nexus Labs: Viktor"

[19:06] You: How is Viktor connected to Rust?

        Agent calls: memory_graph_path("Viktor", "Rust")
        → "Viktor →[CTO_OF]→ Nexus Labs →[BUILDS]→ SkyNet-X →[USES]→ Rust"

Plugin config

{
  "plugins": {
    "entries": {
      "memory-graph": {
        "enabled": true,
        "config": {
          "autoIngest": true,
          "extractionModel": "gpt-4o-mini",
          "dbPath": "~/.openclaw/data/memory-graph.db",
          "maxHops": 5,
          "minConfidence": 0.7
        }
      }
    }
  }
}

Set autoIngest: false to disable auto-ingestion and only use manual tool calls.

🧪 Query Examples

The NL query engine understands 12+ question patterns:

📊 Graph Visualization

graph LR
    classDef person fill:#3b82f6,stroke:#1d4ed8,color:#fff
    classDef company fill:#f97316,stroke:#c2410c,color:#fff
    classDef project fill:#8b5cf6,stroke:#6d28d9,color:#fff
    classDef tool fill:#10b981,stroke:#047857,color:#fff

    Alice[Alice - CTO]:::person
    Bob[Bob - Engineer]:::person
    TechCorp[TechCorp]:::company
    Platform[Platform Team]:::project
    K8s[Kubernetes]:::tool
    Go[Go]:::tool
    PG[PostgreSQL]:::tool

    Alice -->|CTO_OF| TechCorp
    Alice -->|LEADS| Platform
    Alice -->|USES| K8s
    Alice -->|USES| Go
    Alice -->|USES| PG
    Bob -->|MEMBER_OF| Platform
    Bob -->|WORKS_AT| TechCorp

⚙️ Configuration

LLM Provider

Works with any OpenAI-compatible API — OpenAI, Anthropic (via proxy), Ollama, LiteLLM, vLLM, 9router, etc.

Examples:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic via LiteLLM/9router
export OPENAI_BASE_URL="http://127.0.0.1:4000/v1"
export MEMORY_GRAPH_MODEL="claude-3-5-haiku-20241022"

# Ollama (free, local)
export OPENAI_BASE_URL="http://localhost:11434/v1"
export MEMORY_GRAPH_MODEL="llama3.1"

Domain Hints (optional)

Improve extraction accuracy for your specific domain:

{
  "domains": [{
    "name": "software",
    "entityHints": ["Person", "Repository", "Language", "Framework", "Service"],
    "relationHints": ["MAINTAINS", "USES", "DEPENDS_ON", "DEPLOYS_TO"]
  }]
}

🏗️ Architecture

┌─────────────────────────────────────────────┐
│            MemoryGraph API                   │
├─────────────────────────────────────────────┤
│  Ingest  │  Query   │  Search  │  Export    │
├──────────┼──────────┼──────────┼───────────┤
│ LLM      │ NL Query │ FTS5     │ Mermaid   │
│ Extractor│ Engine   │ Hybrid   │ DOT/JSON  │
├──────────┴──────────┴──────────┴───────────┤
│         GraphEngine (SQLite + WAL)          │
│  Entities │ Relationships │ FTS5 Index      │
└─────────────────────────────────────────────┘

• SQLite — Single file, WAL mode, FTS5 full-text search
• LLM extraction — Any OpenAI-compatible provider
• NL Query Engine — 12+ regex patterns + smart entity-name fallback
• Graph traversal — BFS pathfinding up to 5 hops
• Deduplication — Levenshtein-based entity merging
• Persistence — Survives process restarts, session resets, and agent reboots

📈 Test Results

✓ Unit tests: 38/38 pass
✓ NL Query accuracy: 10/10 (local), 9.5/10 (plugin E2E)
✓ Path finding: 4/4 pass
✓ Edge cases: graceful handling, zero crashes
✓ Zero hallucination: no fabricated relationships
✓ Persistence: data survives /new, /reset, gateway restart

🤝 Contributing

PRs welcome! See CONTRIBUTING.md.

git clone https://github.com/KLSGG/agent-memory-graph
cd agent-memory-graph
npm install
npm test       # 38 tests
npm run dev    # Watch mode

📄 License

MIT — Use it however you want.