Metadata-Version: 2.4
Name: chip-memory
Version: 1.1.0
Summary: Local-first, self-organizing memory layer for AI agents. Auto-absorbs knowledge from shell history, git, and Claude Code sessions. MCP-native.
Author-email: Ivan Chakurov <ivan@chakurov.dev>
License: MIT License
        
        Copyright (c) 2026 Ivan Chakurov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/chakurov1907-cyber/chip-memory
Project-URL: Issues, https://github.com/chakurov1907-cyber/chip-memory/issues
Keywords: ai,agents,memory,rag,semantic-search,local-first,self-hosted,mcp,knowledge-graph
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
Requires-Dist: pytest-cov<7.0,>=4.0; extra == "dev"
Provides-Extra: embeddings
Requires-Dist: numpy<3.0,>=1.24; extra == "embeddings"
Requires-Dist: sentence-transformers<4.0,>=2.2.0; extra == "embeddings"
Requires-Dist: torch<3.0,>=2.0; extra == "embeddings"
Provides-Extra: llm
Provides-Extra: rerank
Requires-Dist: flashrank<1.0,>=0.2.10; extra == "rerank"
Provides-Extra: tui
Requires-Dist: textual<2.0,>=0.40; extra == "tui"
Provides-Extra: telegram
Requires-Dist: telethon<2.0,>=1.28; extra == "telegram"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# 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](https://github.com/chakurov1907-cyber/chip-memory/actions/workflows/test.yml/badge.svg)](https://github.com/chakurov1907-cyber/chip-memory/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/chip-memory.svg)](https://pypi.org/project/chip-memory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

![demo](assets/demo.gif)

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

## Quick start — 60 seconds

```bash
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:

```json
{
  "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`):**

```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

```bash
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

```bash
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

```bash
pip install chip-memory
```

From source:

```bash
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

```bash
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

```bash
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:

```bash
pip uninstall chip-memory
```

## Architecture

See [ARCHITECTURE.md](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](PRIVACY.md) — local-only, no telemetry, redaction
- [SECURITY.md](SECURITY.md) — disclosure, auth, path traversal
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to build and contribute
- [CHANGELOG.md](CHANGELOG.md) — release history

## License

MIT. See [LICENSE](LICENSE).
