TrueMem Setup Guide
Giving your AI agent a real memory — knowledge graph, entity resolution, temporal awareness.
Last updated: March 21, 2026
🤔 The Problem
AI assistants are brilliant in the moment — but they have no real memory. Every conversation starts from scratch.
❌ "What was my preference again?"
You've told your AI assistant your preferences ten times. It asks again tomorrow. Every. Single. Time.
❌ "We decided this last week"
Important decisions made in conversation are gone by next session. No institutional memory.
❌ "Who was working on that?"
People, projects, relationships — all lost. Your AI can't build a picture of your world over time.
❌ "But things changed since then"
Even if an AI could remember, facts change. Old information needs to be superseded, not just piled up.
💡 The Solution
TrueMem automatically captures facts from your conversations and stores them in a knowledge graph — a web of connected, time-aware facts that your AI can search and use naturally.
✅ Automatic Capture
No manual work. TrueMem listens to conversations and extracts key facts — decisions, preferences, relationships — automatically.
✅ Automatic Recall
When you ask a question, relevant facts are pulled from memory and injected into the conversation — seamlessly, behind the scenes.
✅ Time-Aware
Facts have dates. When something changes, the old fact is marked as expired and the new one takes over. Your AI knows what's current.
✅ Connected Knowledge
Facts aren't just a flat list. They form a graph — "You prefer dark mode," "You use OpenClaw," "OpenClaw runs on VPS" — all linked.
⚙️ How It Works
Three invisible steps that happen automatically, every conversation.
You chat naturally
You talk to your AI assistant like normal. No special commands, no tagging, no extra effort. Just have your conversation.
TrueMem captures facts
The Librarian subsystem runs periodically, batch-extracting structured facts from your conversations using Claude Opus. It extracts typed entities (People, Clients, Projects, Findings, Decisions, Tools, and more) and typed relationships (WorksOn, Diagnosed, Pays, Blocks, etc.) and writes them directly to the knowledge graph via a direct write pipeline — no intermediate LLM re-extraction. You can also manually store facts with the truemem_store tool, which writes directly to the graph with embeddings. All writes bypass Graphiti's LLM extraction entirely.
Next time, your AI remembers
When you start a new conversation, TrueMem searches the knowledge graph using hybrid search (BM25 + semantic + graph traversal) with cross-encoder reranking for precision. Results are scored with temporal decay (recent facts rank higher) and filtered with MMR dedup (removes near-duplicates). Entity profiles, relationship structure, and community summaries are injected into the AI's context. The AI responds as if it's always known — because now it has.
🔍 Before vs. After
What changes when your AI has real memory.
🎯 Use Cases
TrueMem is valuable anywhere an AI needs to build understanding over time.
Development Teams
Your AI remembers tech decisions, architecture choices, who owns what, and project deadlines.
Client Management
Track client preferences, past conversations, agreed terms, and relationship history.
Operations
Remember infrastructure decisions, deployment configs, incident learnings, and runbook updates.
Personal Assistant
Your AI knows your preferences, habits, schedule patterns, and ongoing tasks without being told twice.
Research
Build a growing knowledge base across research sessions. Facts, sources, and connections accumulate naturally.
Multi-Agent Teams
Multiple AI agents share a knowledge graph while maintaining their own isolated memory spaces.
🔧 Setup — One Config File
All TrueMem settings live in a single file: truemem.config.json.
No hunting through env vars, Docker files, or plugin configs.
Copy the template
cp truemem.config.example.json truemem.config.json — then fill in your OpenAI API key and Neo4j password. Everything else has sensible defaults.
Fill in your .env
cp .env.example .env — edit .env with your secrets, URLs, API keys, and model names. Docker reads this directly.
Start the stack
cd infra && docker compose up -d — Neo4j, LLM proxy, and Graphiti all start with your config. Install the plugin in OpenClaw and you're running.
📄 What's in truemem.config.json
Values starting with $ are resolved from .env at runtime. Literal values pass through unchanged.
graphiti — Graphiti URL, Neo4j URLs and password ($VAR refs)
embedder — Embedding API key, model, base URL ($VAR refs)
llmProxy — LLM proxy keys, model, base URL ($VAR refs)
librarian — LLM provider, model, API key, dedup threshold, max tokens, write delay, noise patterns
schema — entity types, edge types, domain, extraction prompt, few-shot examples, groupRouting
plugin — store mode, auto-recall, relevance threshold, temporal decay, MMR, timeouts, recall cache, skip gate, noise penalty, recall feed, entity tracking
cleanup — Weekly graph hygiene: dedup merging, noise removal, orphan cleanup. Configurable schedule, phases, similarity threshold, noise patterns
infra — Docker image tags, memory limits (Neo4j, Graphiti, proxy)
How Config Flows
Two files, one change = one place. No generation step, no drift.
.env
All actual values
truemem.config.json
Structure + $VAR mappings
resolveConfig()
$VAR → actual value
Code + Docker
Resolved values everywhere
TypeScript code resolves $VAR from config. Docker reads .env directly. Python patches read env vars via Docker.
Plugin / Librarian (TypeScript)
Reads truemem.config.json, resolves $VAR references from .env at startup. One resolved config object for all code.
Graphiti Patches (Python)
Reads env vars set by Docker Compose (from .env). Schema types (ENTITY_TYPES, EDGE_TYPES) build dynamic registries.
🏗️ Under the Hood
Two memory systems, one AI. Here's how QMD and TrueMem fit together inside OpenClaw.
💬 Your Chat
Natural conversation
🧩 OpenClaw Agent
Your AI assistant
📓 QMD — Your Journal
QMD Plugin
memory_search & memory_get
📁 Markdown Files
MEMORY.md, daily notes, archives
Deliberate · Curated · You write it
🧠 TrueMem — Your Implicit Memory
TrueMem Plugin
Auto-recall & direct store
📚 Librarian
Batch extraction (Claude Opus)
✍️ Direct Write
Entity nodes + edges + embeddings
🕸️ Neo4j Graph
Temporal knowledge graph
Automatic · Time-aware · Direct writes
Both memory systems feed into the same OpenClaw agent. QMD provides your curated documents and notes. TrueMem's Librarian batch-extracts facts using Claude Opus and writes them directly to Neo4j via entity node + entity edge APIs (with OpenAI embeddings). No intermediate LLM re-extraction. Everything runs locally on your server — your data stays yours.
🌟 Key Benefits
Why TrueMem matters for your AI workflow.
Privacy First
Everything runs on your own server. Your knowledge graph, your data, your control. Nothing leaves your infrastructure.
Zero Effort
No manual tagging, no note-taking, no special commands. Just talk. TrueMem handles the rest automatically.
Time-Aware
Facts expire naturally. When you change your mind or things evolve, old facts are superseded — not duplicated.
Non-Invasive
Works alongside your existing memory tools (like QMD). TrueMem adds a new layer without replacing anything.
Agent Isolation
Each AI agent gets its own memory space. They can't read or write to each other's facts — enforced by the platform, not by trust.
Cost Efficient
Fact extraction uses Claude Opus via your Anthropic Max subscription ($0 marginal cost). Direct writes to Neo4j use OpenAI embeddings (~$0.00006/fact). No intermediate LLM re-extraction. Runs on a single VPS.
🤝 TrueMem + QMD: Better Together
OpenClaw already has QMD — a curated markdown memory system. TrueMem doesn't replace it. They serve different purposes and together give your AI two complementary kinds of memory.
💡 How they work together
QMD is your deliberate knowledge — the things you take the time to write down. MEMORY.md, daily notes, project docs, runbooks. It's your historical record and reference library. When you need the AI to know something specific and permanent, you put it in QMD.
TrueMem catches everything else — the facts that emerge naturally from conversations but nobody would bother to write down. "You prefer dark mode." "We decided to use Rust for the new project." "The deadline moved to April." These details matter, but they'd be lost without automatic capture.
Together, your AI has both intentional knowledge (QMD) and organic knowledge (TrueMem). It can reference your carefully maintained docs and recall that offhand preference you mentioned three weeks ago. That's real memory.
🛡️ Production Hardened
TrueMem is designed for real-world reliability. No silent failures, no data loss.
Proxy Monitoring
Per-key usage stats, rate-limit tracking, and optional webhook alerts when all keys are exhausted. Stats persist across restarts.
No Silent Data Loss
Health gates reject new messages when Neo4j is down or the queue is full. The plugin reports honest errors instead of false "Stored" confirmations.
Cross-Group Authorization
Agents can only delete their own facts. Ownership is verified before every delete operation — enforced at the code level, not by trust.
Self-Healing
Backend health is tracked per job cycle. When Neo4j recovers, the system automatically resumes accepting work. No manual intervention needed.
🚀 v2.0 Features (March 2026)
Major release. Plugin refactored from a single 2,200-line file into 8 focused modules. New scoring, curation, and recall features.
New Tool: truemem_path
Multi-hop graph traversal. Ask "How is entity A connected to entity B?" and get the actual relationship chain through the knowledge graph.
truemem_path({from: "Acme Corp", to: "Tampa"})
→ Path 1 (2 hops):
Acme Corp --[ServesArea]--> Tampa FL
• Acme Corp serves the Tampa FL area
Uses Cypher variable-length pattern matching on Neo4j. Configurable max depth (1-6 hops).
Entity-Type Half-Lives
Not all facts are equal. Client facts should persist forever. Routine/bottleneck facts should fade. Per-entity-type temporal decay:
| Entity Type | Half-Life |
|---|---|
| Client, Person, Competitor, Location, Decision, Preference, Service, IncomeStream, Policy, Agent | Never decays |
| Contract, Tool, Process, Integration, Channel, Contractor | 365 days |
| Campaign, Project, Goal, ROI | 180 days |
| Prospect, Finding, Deliverable, Automation | 90 days |
| Routine, Bottleneck | 30 days |
Config: "entityHalfLivesEnabled": true
Tiered Injection (Hot/Warm/Cold)
Auto-recall now formats facts based on relevance score:
- Hot (≥0.7) — Full detail with relationship structure, capped at 300 chars
- Warm (≥0.4) — Truncated text, 100 chars max
- Cold (<0.4) — Entity → relationship → target only (no fact text)
More coverage in the same token budget. Config: "tieredInjectionEnabled": true
Feedback Loop
Tracks whether the assistant actually used injected facts. At agent_end, checks word overlap between the assistant's response and injected fact text. Referenced facts get their access count bumped, feeding into rehearsal stability.
Rehearsal Stability
Frequently-referenced facts resist temporal decay. Each access logarithmically extends the effective half-life (capped at 3x). Formula: min(3, 1 + 0.3 * ln(1 + accesses))
Schema Expansion
Expanded from 14 to 26 entity types and 16 to 27 edge types. New types include Location, Competitor, Campaign, Contract, IncomeStream, Automation, Integration, and more. The "schema is the gate" principle: if there's no entity type for a fact, it can't enter the graph.
Other v2.0 Improvements
- Content-hash dedup — Prevents duplicate auto-captures within 30s window
- Code-heavy skip — Skips recall on code-heavy messages (low alpha ratio)
- Length normalization — Penalizes verbose facts that dominate via keyword density
- Private tags —
<private>...</private>content stripped from both recall and capture - Configurable noise penalty weights — Fine-tune how infrastructure vs. value entity types are ranked
- Session summaries — Librarian generates heuristic session summaries per agent (no extra LLM call)
🚀 v1.30 Features
Performance and quality improvements added in the latest release.
Recall Cache
Reuses the last search result until the topic shifts or N messages pass. Eliminates redundant Graphiti queries and cuts recall latency on repeated topics to near zero. Configured via plugin.recallCache.
Skip Gate
Skips auto-recall for trivial messages (ok, done, yes, thanks, etc.) — saves 4–6 seconds per skipped message. Pattern list is configurable in plugin.skipGate.
Noise Penalty
Deprioritizes low-signal entity types (Tool, Finding, Bottleneck) in auto-recall scoring and boosts high-value types (Client, Person, Service). Configured via plugin.noisePenalty.
Recall Feed
Optional Telegram feed that logs every auto-recall: which facts were injected, scores, and cache status. Useful for monitoring and tuning recall quality. Enable in plugin.recallFeed.
Group Routing
Multi-agent isolation — each agent's facts go to their own group in the graph. Shared knowledge lives in system-shared. Configured via schema.groupRouting.
Weekly Cleanup
Automated graph hygiene runs weekly: merges near-duplicate facts, removes noise nodes, and prunes orphan entities. Keeps the knowledge graph lean without manual maintenance.
💾 Store Modes
TrueMem supports three store modes, configured in plugin.storeMode:
enriched — Sends conversations to Graphiti's /messages endpoint for full entity resolution and relationship extraction. Highest quality, slower.
direct — Writes entity nodes and edges directly to the graph with embeddings. Faster, bypasses Graphiti's LLM extraction entirely.
fallback — Tries enriched first; if it fails (timeout, error), falls back to direct. Best of both worlds for production reliability.