The Problem
You run multiple AI agents — Claude Code for development, autonomous agents for tasks. They each maintain their own context and forget everything between sessions. When one agent discovers something important, the others never learn about it.
How It Works
Typed Memory
Events are immutable history. Facts upsert by key — new facts supersede old ones. Statuses track current state. Decisions record choices and reasoning. Each type has its own lifecycle, decay rules, and mutation semantics.
Unified Storage
Every memory lives in a single Postgres database: pgvector (HNSW) for semantic vector search and structured tables for queries, entities, and full-text search. Get both "find memories similar to X" and "give me all facts with key Y" from the same system — one container, no separate vector service.
Multi-Path Search
Search runs up to three retrieval paths in parallel, fused with weighted Reciprocal Rank Fusion:
- Vector search — Cosine similarity via pgvector (HNSW, with iterative index scans on pgvector 0.8+ so tenant-scoped queries don't lose recall)
- Full-text search — Postgres tsvector (
websearch_to_tsquery+ts_rank_cd), with an opt-in accent-folding config for mixed-language corpora (BM25_TSCONFIG=zengram_multi) - Entity graph (opt-in) — entities in the query expand one hop over the co-occurrence graph the write path already maintains, pulling in associatively-related memories (
GRAPH_RETRIEVAL_ENABLED)
An optional cross-encoder reranker (RERANK_ENABLED) then re-scores the fused pool by reading query and document together — the highest-leverage precision upgrade in the stack (on our private bilingual production corpus it roughly doubled MRR; measure yours with the eval harness). Works with any TEI / Infinity / vLLM / Jina / Cohere-style /rerank endpoint and degrades gracefully to fused order on outage.
Final ranking blends the fused RRF signal with vector similarity (or the rerank score when enabled), then weights confidence decay, access frequency (capped), temporal proximity, and importance — items found by multiple paths genuinely rank higher. 98.4% retrieval accuracy on LongMemEval.
Built for Multi-Agent
- Cross-agent briefings — "What happened since I was last here?" returns updates from all other agents
- Cross-agent corroboration — when a second agent independently stores the same fact, it's recorded as an observation (
observed_by), not dropped as a duplicate - Credential scrubbing — API keys, JWTs, passwords, cloud/service tokens automatically redacted before storage
- Entity extraction — Regex + alias cache at write time
- LLM consolidation — Periodic background process merges duplicates, resolves contradictions, discovers connections
Benchmarks
Evaluated on LongMemEval, the academic benchmark for long-term conversational memory:
The benchmark uses cosine similarity only — none of the API's multi-path features (keyword full-text, temporal boost) were used. Full methodology and per-category breakdown.
LongMemEval tests single-agent chat recall. Zengram is built for multi-agent coordination — features like cross-agent briefings, typed memory, entity extraction, and credential scrubbing aren't measured by this benchmark but are core to production use.
How It Compares
Quick Start
git clone https://github.com/ZenSystemAI/Zengram.git
cd Zengram
cp .env.example .env
# Edit .env — set BRAIN_API_KEY and your embedding provider key
docker compose up -d
# Verify
curl http://localhost:8084/health
# Store your first memory
curl -X POST http://localhost:8084/memory \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_KEY" \
-d '{
"type": "fact",
"content": "The API uses port 8084 by default",
"source_agent": "my-agent",
"key": "api-default-port"
}'
Adapters
MCP Server (Claude Code, Cursor, Windsurf)
13 tools: brain_store, brain_search, brain_briefing, brain_query, brain_stats, brain_consolidate, brain_entities, brain_delete, brain_update, brain_export, brain_import, brain_reflect, brain_research.
{
"mcpServers": {
"zengram": {
"command": "node",
"args": ["/path/to/zengram/mcp-server/src/index.js"],
"env": {
"BRAIN_API_URL": "http://localhost:8084",
"BRAIN_API_KEY": "your-key"
}
}
}
}
Or install via npm: npm install -g @zensystemai/zengram-mcp
Claude Code Skills
Copy adapters/claude-code/sessionend/ to your project's .claude/skills/ to get the /sessionend ritual — structured session reflections stored directly to Zengram. Full guide.
Bash CLI
- Bash:
./adapters/bash/brain.sh store --type fact --content "Server migrated" - Any HTTP client: Plain REST — full reference
Documentation
Roadmap
Recently shipped: cross-encoder reranking stage, entity-graph retrieval path, weighted RRF, self-hosted encoder support (local endpoints + instruction prefixes + staged re-embed), agentic iterate-until-sufficient retrieval (brain_research) with grounded [mem:<id>] citations, pgvector migration (single-Postgres storage), multi-collection support, on-demand LLM reflection, temporal validity — full changelog
Coming next: Automatic memory capture, hosted docs, LangChain/LlamaIndex integration
Contributing
Contributions welcome! See CONTRIBUTING.md.
See Also
- OpenClaw Memory Toolkit — Long-term memory for OpenClaw agents.
License
MIT — see LICENSE.
