chip-memory 1.1.0__tar.gz

chip_memory-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

chip_memory-1.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+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).

chip_memory-1.1.0/README.md

@@ -0,0 +1,228 @@
+# 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).

chip_memory-1.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chip-memory"
+version = "1.1.0"
+description = "Local-first, self-organizing memory layer for AI agents. Auto-absorbs knowledge from shell history, git, and Claude Code sessions. MCP-native."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Ivan Chakurov", email = "ivan@chakurov.dev"},
+]
+keywords = ["ai", "agents", "memory", "rag", "semantic-search", "local-first", "self-hosted", "mcp", "knowledge-graph"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    # All heavy deps (numpy, sentence-transformers, torch) are lazy-imported
+    # inside _get_model() and _get_or_compute_embeddings() so a fresh install
+    # is just stdlib. To enable semantic search, install the `embeddings` extra:
+    #     pip install chip-memory[embeddings]
+    # pyyaml: required by eval.py for loading the NamedThingBench YAML fixture
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0,<9.0",
+    "pytest-cov>=4.0,<7.0",
+]
+embeddings = [
+    "numpy>=1.24,<3.0",
+    "sentence-transformers>=2.2.0,<4.0",
+    "torch>=2.0,<3.0",
+]
+llm = [
+    # For --provider groq or openai (the heuristic extractor needs no API key)
+]
+rerank = [
+    "flashrank>=0.2.10,<1.0",
+]
+tui = [
+    "textual>=0.40,<2.0",
+]
+telegram = [
+    "telethon>=1.28,<2.0",
+]
+mcp = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+chip-memory = "chip_memory.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/chakurov1907-cyber/chip-memory"
+Issues = "https://github.com/chakurov1907-cyber/chip-memory/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+chip_memory = ["py.typed", "dashboard/static/*.html", "dashboard/static/*.json", "dashboard/static/vendor/*.js"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+# F401 (unused imports): allowed for lazy/optional-import guards — see auto_write.py
+# and tui.py where imports are wrapped in try/except ImportError.
+# F841 (unused local): allowed for argparse sub-parser bindings (the name must
+# be in scope for argparse to dispatch on it).
+line-length = 100
+extend-exclude = []
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = [
+    "E501",  # line-too-long (we judge this by hand, not by tool)
+    "F401",  # unused-import (lazy guards + argparse patterns)
+    "F841",  # unused-local (argparse subparser vars + tui placeholders)
+]

chip_memory-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chip_memory-1.1.0/src/chip_memory/__init__.py

@@ -0,0 +1,31 @@
+"""
+chip_memory — local-first, self-organizing memory layer for AI agents.
+
+Inspired by how microchips work: isolated nodes (transistors) organized in
+layers, with a daemon (electricity) always running, become a CPU (a brain).
+
+Public API:
+  - chip_memory.search   — semantic search over the brain
+  - chip_memory.health   — brain health score + per-domain stats
+  - chip_memory.auto_write  — extract nodes from a transcript
+  - chip_memory.pending  — process pending/ → write nodes
+  - chip_memory.seed     — seed demo nodes for trying the system
+  - chip_memory.rebalance — adjust importance/heat of existing nodes
+  - chip_memory.daemon   — the always-on loop
+  - chip_memory.server   — tiny HTTP API (run separately)
+"""
+__version__ = "1.1.0"
+__all__ = [
+    "api",
+    "auto_write",
+    "daemon",
+    "dashboard",
+    "health",
+    "node",
+    "paths",
+    "pending",
+    "rebalance",
+    "search",
+    "seed",
+    "server",
+]