Skip to main content

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.

CI PyPI version License: MIT Python 3.10+

demo

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.

License

MIT. See LICENSE.

Metadata

Release files for chip-memory 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chip-memory 1.1.0
File Size Uploaded Provenance Actions
chip_memory-1.1.0.tar.gz 533.3 kB Without provenance Details for chip_memory-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for chip-memory 1.1.0
File Interpreter ABI Platform Actions
chip_memory-1.1.0-py3-none-any.whl Python 3 none any Details for chip_memory-1.1.0-py3-none-any.whl

Total release size: 1.0 MB

Release files / chip_memory-1.1.0.tar.gz

Download URL chip_memory-1.1.0.tar.gz
Size 533.3 kB
Tags Source
SHA-256 checksum
How to use checksums
478b26aab10a5f89ae1bbc7412aad43edf4c925ea10b7a28c560b0eb84894531
BLAKE2b-256 checksum
How to use checksums
e06429ca06fe0f5fc5b44f65e2e661e0d9a00669aa8de55adb56bbbfb295ad0a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / chip_memory-1.1.0-py3-none-any.whl

Download URL chip_memory-1.1.0-py3-none-any.whl
Size 500.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79da2da2817f3c08af36f377ecaa961e8b61105291f486bf4167b5729174b101
BLAKE2b-256 checksum
How to use checksums
5c3f34395a8b377b323df51bda742e2352f557e0c1e2cec5eb6bbdf75e344128
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for chip-memory 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page