chip-memory 1.1.0

Local-first, self-organizing memory layer for AI agents. Auto-absorbs knowledge from shell history, git, and Claude Code sessions. MCP-native.

chip-memory

The local-first agent brain. A temporal knowledge graph, human-in-the-loop review, and full provenance, running entirely on your machine with zero cloud and no required LLM.

AI agents forget everything when the session ends. chip-memory fixes that — local, free, learns from use.

Quick start — 60 seconds

pip install chip-memory
chip-memory seed                            # 15 demo nodes across 4 domains
chip-memory search "Hall of Light"          # hybrid search, sub-millisecond
chip-memory think "who works at Acme Corp"  # cited evidence + knowledge gaps

That's it. The brain is plain JSON on disk. Back it up with cp.

MCP for Claude Desktop / Claude Code:

Add this to your Claude Desktop config and restart:

{
  "mcpServers": {
    "chip-memory": {
      "command": "chip-memory",
      "args": ["mcp"]
    }
  }
}

Your agent now has memory_search, memory_remember, memory_context_for, memory_think, and memory_bump as native tools — persistent memory across every session.

Features

• 🏠 Local-first — all data is plain JSON files on disk. No cloud, no account, no API key needed. Back it up with cp.
• 🚫 Zero LLM required — core search and linking runs on pure stdlib. No embeddings, no torch, no model download for daily use.
• 🔗 Temporal knowledge graph — typed edges with bi-temporal validity (valid_from / valid_to). Query "where did Alice work in 2023?" or "who currently runs Acme?" with as_of semantics.
• ⏳ Bi-temporal edges — single-valued predicates auto-supersede (old facts get valid_to + superseded_by, never deleted). Multi-valued predicates just append.
• 🧠 Think mode — chip-memory think "who works at Acme" returns cited evidence from the brain, explicit knowledge gaps, and (via MCP sampling) fluent prose synthesized by your host LLM — no extra key required.
• 🔗 Connect queries — chip-memory connect "Alice" "Bob" finds the multi-hop path (up to 3 hops) between any two entities through the typed edge graph.
• 📜 Provenance + why — every node tracks its source (git, user-correct, signal, manual), trust confidence, and access history. chip-memory why <id> prints the full audit trail.
• 🔍 Hybrid search — 0.7 × vector + 0.3 × BM25, then × heat × importance × trust. --bm25-only skips embeddings entirely and stays sub-millisecond.
• 🌱 Living knowledge graph — links get +0.15 on co-access, decay 1% per cycle, and are severed below 0.10. The graph mirrors how you actually use it.
• 🚦 Signal detector — real-time message scoring classifies corrections (even natural language: "no, the interval is 5 minutes not 10"), high-signal knowledge, and low-signal chit-chat — all with zero LLM.
• 🔗 MCP-native — native Model Context Protocol server. Any MCP client (Claude Desktop, Claude Code, Cursor) gets persistent memory tools with no plugins or glue code.
• 👁 Human review workflow — chip-memory review shows a review queue before anything enters the brain. Guided mode, strict mode, or auto mode.
• 📦 Zero deps — pip install chip-memory installs zero network dependencies. Optional extras add embeddings, reranking, TUI, or LLM extraction behind lazy imports.

Comparison

Feature	chip-memory	Mem0	Zep / Graphiti	Letta	Cognee
Local-first	✅ Local JSON	❌ Cloud	❌ Cloud	❌ Cloud	❌ Cloud
No LLM required	✅ Zero LLM for core	❌ LLM-dependent	❌ LLM-dependent	❌ LLM-dependent	❌ LLM-dependent
Temporal / bi-temporal graph	✅ Bi-temporal edges, local	❌ No	⚠️ Temporal via cloud Neo4j	❌ No	❌ No
Human review workflow	✅ Review queue (guided/strict/auto)	❌ No	❌ No	❌ No	❌ No
Provenance / why command	✅ Per-node provenance + trust	⚠️ Partial	⚠️ Partial	❌ No	❌ No
Cost	$0 (free, MIT)	💰 SaaS	💰 SaaS	💰 SaaS	💰 SaaS
MCP-native	✅ Native MCP server	✅ MCP	⚠️ API wrapper	✅ MCP	❌ No
Secret redaction	✅ 17 patterns, pre-write	❌ No	❌ No	❌ No	❌ No

Where they're ahead

• Managed scale — Mem0 and Zep handle 100k+ nodes with hosted infrastructure. chip-memory is optimized for the sweet spot (~5k nodes) on a single machine.
• Ecosystem — Mem0, Letta, and Cognee have larger communities and more integrations. chip-memory is newer and growing.
• Team size — hosted solutions have dedicated support, SLAs, and enterprise features. chip-memory is MIT — community-supported.

MCP integration — Claude Desktop

The native MCP server gives Claude persistent memory across sessions.

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "chip-memory": {
      "command": "chip-memory",
      "args": ["mcp"]
    }
  }
}

Claude Code auto-discovers the MCP server when installed. No additional config needed.

Available MCP tools:

Tool	Description
memory_search	Semantic search over the brain
memory_remember	Store a fact
memory_context_for	Get relevant context for a prompt
memory_think	Answer with cited evidence + gaps (uses host LLM via MCP sampling)
memory_bump	Boost a node's heat on access

Reproducible eval

chip-memory eval

✅ PASS  P@3=1.000  P@5=1.000  13/13 passed

Benchmark: NamedThingBench (13 queries) — a curated set of entity-resolution queries over a seeded fixture brain. Run it yourself in under 2 seconds.

Who this is for

• Agent developers using Claude Code, Aider, Hermes, OpenClaw, or your own scripts — drop a session transcript into pending/ and the brain extracts memory nodes automatically.
• People running local models who want memory that doesn't need a cloud, an account, or an API key for the brain itself.
• Hobbyists tired of paying for embeddings. The brain runs on stdlib — install chip-memory[embeddings] (~800MB) only when you want semantic search.

The problem it solves

Without chip-memory, every agent session starts blank:

You: "what was that uv trick for installing tools?" Agent: "I don't have memory of previous conversations."

With chip-memory:

You: "what was that uv trick for installing tools?" Agent: [reads brain] "Found it:

• uv is the fastest way to install Python tools in 2026. uvx ruff runs ruff without polluting your system Python.
• linked to: 'When debugging a Python script that crashes deep in a third-party library, set PYTHONFAULTHANDLER=1 first...'"

The brain remembered. You didn't have to.

Quick reference

chip-memory search "debug python"                   # hybrid search
chip-memory think "what's the deployment setup"     # cited evidence + gaps
chip-memory connect "Alice" "Bob"                   # multi-hop path
chip-memory why <node_id>                           # provenance + audit trail
chip-memory recall yesterday                        # episodic timeline recall
chip-memory absorb --dry-run                        # preview machine knowledge
chip-memory review                                  # review queue
chip-memory map hubs                                # top connected nodes
chip-memory timeline                                # brain activity log
chip-memory dashboard                               # web dashboard (127.0.0.1:8732)
chip-memory export "topic" -o topic.md              # markdown export
chip-memory health                                  # brain health score

Install

pip install chip-memory

From source:

git clone https://github.com/chakurov1907-cyber/chip-memory
cd chip-memory
pip install -e .                    # stdlib only
pip install -e ".[embeddings]"      # + vector search (torch + sentence-transformers)

Develop

git clone https://github.com/chakurov1907-cyber/chip-memory
cd chip-memory
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest                              # 476 tests, ~11s
chip-memory --help

How scoring works

hybrid    = 0.7 × cosine_sim + 0.3 × normalized_bm25
score     = hybrid × heat × importance × (0.6 + 0.4 × trust_confidence)

• cosine_sim — from all-MiniLM-L6-v2 (optional, behind [embeddings])
• BM25 — pure stdlib, no sklearn
• heat — decays 5% per cycle, boosted by access × importance
• trust_confidence — source-based (git-fix: 0.9, user-correct: 0.85, manual: 0.8, signal: 0.6)

Honest limits

• Scale: works fine to ~5k nodes. Past that, search latency climbs because the embedder loads one node at a time. For 10k+ nodes, swap in a real vector DB and use chip-memory as the connection layer.
• Multi-tenant: one brain per directory. Use CHIP_BRAIN_DIR env var to switch.
• Concurrency: atomic writes (tmp + os.replace()) prevent corruption, but two simultaneous writers to the same node will lose one's edits.

Uninstall

chip-memory uninstall                # interactive — asks for confirmation
chip-memory uninstall --force        # skip confirmation
chip-memory uninstall --keep-brain   # remove daemon/hooks/config but keep brain data

Removes the daemon process (if running), git post-commit hooks, background watchers, and brain data. To also remove the package itself:

pip uninstall chip-memory

Architecture

See ARCHITECTURE.md for the full system design: heat/decay mechanics, living graph dynamics, bi-temporal edge semantics, signal detector pipeline, MCP integration, and temporal reasoning.

• PRIVACY.md — local-only, no telemetry, redaction
• SECURITY.md — disclosure, auth, path traversal
• CONTRIBUTING.md — how to build and contribute
• CHANGELOG.md — release history

License

MIT. See LICENSE.