agent-memory-graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KL / OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/🧠_Agent_Memory_Graph-Knowledge_that_persists-blueviolet?style=for-the-badge" alt="Agent Memory Graph" />
+</p>
+
+<p align="center">
+  <strong>Give your AI agent a persistent, queryable memory — powered by a local knowledge graph.</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-18%2B-green.svg" alt="Node.js 18+" /></a>
+  <img src="https://img.shields.io/badge/SQLite-FTS5-orange.svg" alt="SQLite FTS5" />
+  <img src="https://img.shields.io/badge/Zero_Config-✓-brightgreen.svg" alt="Zero Config" />
+  <img src="https://img.shields.io/badge/LLM-Any_Provider-purple.svg" alt="Any LLM" />
+</p>
+
+---
+
+## 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
+
+| Feature | Description |
+|---------|-------------|
+| 🧠 **Auto-extraction** | LLM extracts entities & relationships from any text |
+| 🗣️ **Natural language queries** | Ask questions like "Who works at X?" or "What does Y use?" |
+| 🔗 **Path finding** | Discover hidden connections between entities (BFS, up to 5 hops) |
+| 📦 **Single SQLite file** | Zero external deps, fully portable, survives restarts |
+| 🌐 **Domain-agnostic** | Software, crypto, research, CRM, notes — anything |
+| ⚡ **Zero-config** | Works out of the box with any OpenAI-compatible LLM |
+| 🔌 **OpenClaw plugin** | Auto-ingests every conversation, registers query tools |
+| 🔍 **Full-text search** | SQLite FTS5 for fast keyword search |
+| 📊 **Export** | Mermaid, DOT, JSON, CSV for visualization |
+
+---
+
+## 🚀 Quick Start
+
+```bash
+npm install agent-memory-graph
+```
+
+### As a library
+
+```typescript
+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
+
+```bash
+# 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
+
+```bash
+openclaw plugins install agent-memory-graph
+openclaw gateway restart
+```
+
+### 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
+
+```json
+{
+  "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:
+
+| Question | What it does |
+|----------|-------------|
+| "What is Alice working on?" | Find outgoing relationships |
+| "Who works at TechCorp?" | Find people connected to entity |
+| "Where did Bob work before?" | Find PREVIOUSLY_WORKED_AT relations |
+| "What does the team use?" | Find USES relationships |
+| "What is Alice's role?" | Look up role property/relation |
+| "List all people" | Filter by type (normalizes "people" → "Person") |
+| "List all companies" | Type normalization works for all types |
+| "How is A connected to B?" | BFS path finding |
+| "Who suggested X?" | Verb-to-relation matching |
+| "What tools are mentioned?" | Type-based listing |
+
+---
+
+## 📊 Graph Visualization
+
+```mermaid
+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.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENAI_API_KEY` | API key | `sk-local` |
+| `OPENAI_BASE_URL` | API base URL | `http://127.0.0.1:20128/v1` |
+| `MEMORY_GRAPH_API_KEY` | Override API key | — |
+| `MEMORY_GRAPH_BASE_URL` | Override base URL | — |
+| `MEMORY_GRAPH_MODEL` | Override model | `gpt-4o-mini` |
+
+**Examples:**
+
+```bash
+# 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:
+
+```json
+{
+  "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](CONTRIBUTING.md).
+
+```bash
+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](LICENSE) — Use it however you want.
+
+---
+
+<p align="center">
+  <em>Built for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> agents that need to remember.</em>
+</p>

package/config/default.json

@@ -0,0 +1,28 @@
+{
+  "storage": {
+    "path": "./memory-graph.db",
+    "maxSizeMb": 500
+  },
+  "extraction": {
+    "provider": "auto",
+    "model": "auto",
+    "autoExtract": true,
+    "minConfidence": 0.7,
+    "batchSize": 5
+  },
+  "domains": [],
+  "deduplication": {
+    "enabled": true,
+    "similarityThreshold": 0.85
+  },
+  "sync": {
+    "memoryMd": null,
+    "neuralMemory": null,
+    "importOnStart": false
+  },
+  "query": {
+    "maxHops": 3,
+    "maxResults": 10,
+    "includeConfidence": true
+  }
+}

package/config/graph.config.json

@@ -0,0 +1,28 @@
+{
+  "storage": {
+    "path": "./memory-graph.db",
+    "maxSizeMb": 500
+  },
+  "extraction": {
+    "provider": "openai",
+    "model": "kr/claude-haiku-4.5",
+    "autoExtract": true,
+    "minConfidence": 0.7,
+    "batchSize": 5
+  },
+  "domains": [],
+  "deduplication": {
+    "enabled": true,
+    "similarityThreshold": 0.85
+  },
+  "sync": {
+    "memoryMd": null,
+    "neuralMemory": null,
+    "importOnStart": false
+  },
+  "query": {
+    "maxHops": 3,
+    "maxResults": 10,
+    "includeConfidence": true
+  }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../cli/index.ts"],"names":[],"mappings":""}