NeoMemory

Local-first memory engine for AI agents. Give your Claude, GPT, or custom agents persistent, searchable memory with a temporal knowledge graph — all on your machine.

Runtime: Bun >= 1.0 required (uses bun:sqlite for zero-dependency SQLite)

Why NeoMemory?

| | NeoMemory | Mem0 | Zep CE | Letta | |---|-----------|------|--------|-------| | LLM Required | No (rule-based NER) | Yes | Yes | Yes | | Language | TypeScript | Python | Python | Python | | Storage | SQLite (local) | PostgreSQL | PostgreSQL | PostgreSQL | | Knowledge Graph | Built-in (temporal) | No | No | No | | Bi-temporal | Yes | No | No | No | | MCP Native | Yes (11 tools) | No | No | No | | License | Apache 2.0 | Apache 2.0 | MIT | Apache 2.0 |

Features

• Zero-LLM entity extraction — rule-based NER, no API calls needed
• Local-first SQLite — data never leaves your machine
• TypeScript-native — first-class library, not a Python wrapper
• Temporal knowledge graph — 10 entity types, 15 relation types, bi-temporal modeling (validTime + observedAt)
• Three-way retrieval — Profile match + Episode FTS + Graph traversal, fused with Reciprocal Rank Fusion
• Four-layer memory — Working / Profile / Episode / Knowledge Graph
• Multi-agent RBAC — coordinator / worker / readonly roles with per-agent overrides and tenant isolation
• MCP Server — 11 tools for Claude Code and Claude Desktop integration
• REST API + CLI + Portal — multiple access patterns for every use case
• Knowledge graph visualization — interactive web UI with Cytoscape.js
• Import/Export — CLAUDE.md, Claude conversation history (.jsonl), Markdown; export to markdown/json/claude-md
• CJK-friendly search — FTS5 + substring fallback for Chinese, Japanese, Korean
• Memory decay — exponential decay with temporal freshness scoring
• GDPR purge — per-agent hard deletion across all memory layers (episodes, profiles, graph)
• Zero config — works out of the box with SQLite, no external services required

Quick Start

bun add neo-memory

import { NeoMemory } from 'neo-memory'

const mem = await NeoMemory.create()

// Store a memory (auto-classified → profile + episode + knowledge graph)
await mem.store({
  type: 'observation',
  content: 'User prefers bun over npm for package management',
  agentId: 'claude',
})

// Recall memories (three-way RRF fusion)
const result = await mem.recall('package manager', { agentId: 'claude' })
console.log(result.items)

// Build context for LLM system prompt injection
const context = await mem.buildContext('tech stack', {
  agentId: 'claude',
  maxTokens: 2000,
  format: 'markdown',
})

// Trace knowledge graph relationships
const paths = await mem.trace({ entityName: 'TypeScript', maxHops: 2 })

// View entity timeline
const timeline = await mem.timeline({ entityName: 'TypeScript' })

MCP Integration (Claude Code)

claude mcp add neo-memory -s user -- bunx neo-memory --mcp

Available MCP tools:

| Tool | Description | |------|-------------| | neo_store | Store a memory (auto-classified and indexed) | | neo_recall | Recall memories (three-way RRF fusion) | | neo_context | Build formatted context for LLM injection | | neo_profile | Get or update agent profile | | neo_episodes | Search memory episodes | | neo_forget | Soft-delete a memory | | neo_overview | System status overview | | neo_cross_recall | Cross-agent recall (coordinator only) | | neo_agent_overview | View another agent's memories | | neo_trace | Trace entity relationships through knowledge graph (multi-hop) | | neo_timeline | View how facts about an entity evolved over time |

CLI

neo-memory store "User prefers TypeScript strict mode"
neo-memory recall "TypeScript"
neo-memory profile claude
neo-memory episodes "tech stack"
neo-memory import ~/.claude/CLAUDE.md
neo-memory overview
neo-memory portal          # Launch web UI on :3737
neo-memory serve           # Launch REST API on :3210
neo-memory backup
neo-memory restore <file>
neo-memory reembed         # Re-embed all episodes with current provider
neo-memory reindex         # Rebuild FTS search indexes
neo-memory purge --agent claude --gdpr  # GDPR-compliant data removal
neo-memory setup mcp       # Configure Claude Desktop integration

REST API

neo-memory serve
# Server starts on http://localhost:3210

| Method | Path | Description | |--------|------|-------------| | POST | /store | Store episode | | POST | /recall | Three-way retrieval | | GET | /profile/:agentId | Get profile | | POST | /profile | Update profile | | POST | /context | Build LLM context | | POST | /episodes | Search episodes | | DELETE | /episodes/:id | Soft-delete episode | | GET | /overview | System overview | | POST | /cross-recall | Cross-agent recall | | GET | /agents/:agentId/overview | Agent overview | | POST | /graph/trace | Graph entity tracing | | POST | /graph/timeline | Entity fact timeline | | DELETE | /agents/:agentId | Purge agent data | | GET | /health | Health check |

Portal (Web UI)

neo-memory portal
# Opens on http://localhost:3737

Dashboard, search, episode browser, profile editor, interactive knowledge graph visualization, settings & backup management. Set NEO_PORTAL_TOKEN for authentication.

Configuration

# ~/.neo-memory/config.yaml
storage:
  type: sqlite

embedding:
  provider: noop       # noop | ollama | openai

extraction:
  provider: rule       # keyword-based entity/relation extraction

permissions:
  agents:
    claude:
      role: coordinator
    default:
      role: worker

Architecture

┌──────────────────────────────────────────────┐
│  Adapters: MCP │ REST │ CLI │ Portal │ Lib   │
├──────────────────────────────────────────────┤
│  Core Engine                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ Profile  │ │ Episode  │ │  Knowledge   │ │
│  │ Store    │ │ Store    │ │  Graph       │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │Classifier│ │Retriever │ │   Graph      │ │
│  │ (Rules)  │ │(3-way RRF)│ │  Traversal  │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │Permissions│ │ Context │ │   Decay      │ │
│  │ (RBAC)   │ │ Builder │ │   Engine     │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
├──────────────────────────────────────────────┤
│  Storage: SQLite + FTS5 + sqlite-vec (opt)   │
│  Bi-temporal: validTime + observedAt         │
└──────────────────────────────────────────────┘

Docker

docker compose up -d
# REST API → http://localhost:3210
# Portal   → http://localhost:3737

Roadmap

• [x] Phase 1 — Profile + Episode + FTS + MCP + CLI
• [x] Phase 2 — Knowledge Graph (entities, relations, graph traversal)
• [x] Phase 3 — Bi-temporal modeling + import/export + GDPR purge
• [x] Phase 4 — Memory Portal (Web UI) + Docker
• [x] Phase 5 — npm publish + graph tenant isolation + GDPR purge hardening
• [ ] Phase 6 — Documentation site + tutorials
• [ ] Phase 7 — Qdrant vector engine + cloud service (optional hosted version)

License

Apache 2.0