Metadata-Version: 2.4
Name: gr0m-mem
Version: 0.1.0
Summary: Zero-install persistent memory brain for Claude Code and Claude Desktop. Stops re-asking and re-deriving across sessions.
Project-URL: Homepage, https://github.com/MichaelAdamGroberman/gr0m_mem
Project-URL: Issues, https://github.com/MichaelAdamGroberman/gr0m_mem/issues
Project-URL: Changelog, https://github.com/MichaelAdamGroberman/gr0m_mem/blob/main/CHANGELOG.md
Author: Gr0m_Mem contributors
License: MIT
License-File: LICENSE
Keywords: claude,mcp,memory,rag,sqlite,wakeup
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Requires-Dist: mcp<2.0,>=1.26.0
Requires-Dist: networkx<4.0,>=3.4
Requires-Dist: pyyaml<7.0,>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: tiktoken<1.0,>=0.8; extra == 'dev'
Provides-Extra: tokens
Requires-Dist: tiktoken<1.0,>=0.8; extra == 'tokens'
Description-Content-Type: text/markdown

# Gr0m_Mem

Zero-install persistent memory brain for **any** LLM runtime (Claude Code, Claude Desktop, Cursor, Gemini CLI, Continue, Cline, Zed, OpenAI Codex CLI, Aider, raw OpenAI / Anthropic / Gemini APIs, or a local Llama) that **stops the model from re-asking and re-deriving** across sessions.

> **This is the `main` branch — the zero-install core.**
> No ChromaDB, no Ollama, no 1 GB embedding model. Pure CPython stdlib + a couple of pure-Python wheels. `pip install gr0m-mem` and it just works.
>
> For semantic retrieval (ChromaDB HNSW + Ollama embeddings) switch to the [`semantic`](https://github.com/MichaelAdamGroberman/gr0m_mem/tree/semantic) branch.

## Works with any LLM

Gr0m_Mem is universally compatible through three integration paths:

- **MCP server** — Claude Code, Claude Desktop, Cursor, Gemini CLI, Continue, Cline, Zed, OpenAI Codex CLI, and any other [Model Context Protocol](https://modelcontextprotocol.io) client. Setup snippets for every major client in [`docs/integrations.md`](docs/integrations.md).
- **CLI shell-out** — any agent framework that can run shell commands (OpenAI Agents SDK, LangChain, LlamaIndex, Aider, raw API callers): wrap `gr0m_mem wakeup`, `gr0m_mem remember`, and `gr0m_mem search` as tools.
- **Paste-into-system-prompt** — models with no MCP and no tool calling at all: copy [`UNIVERSAL_PROMPT.md`](UNIVERSAL_PROMPT.md) into your system prompt and the model will drive the CLI via shell.

The loop-prevention protocol is the same across all three paths.

## The problem

Claude forgets everything when a session ends. Next time you talk to it:

- It re-introduces itself.
- It asks what you're working on — again.
- It re-derives the same architectural decision you already locked in yesterday.
- It loses track of which features shipped and re-suggests them.

Other memory systems try to fix this with "let an LLM decide what to remember." That path is expensive, loses context, and still leaks reasoning. Gr0m_Mem takes the other path: **record everything important explicitly, surface it at session start, and refuse to contradict it without you saying so.**

## How it fixes the loop

Four tools (and two Claude Code hooks) are the entire product:

| When | Tool | Effect |
|---|---|---|
| Session start | `mem_wakeup` | Returns a token-budgeted snapshot of identity / preferences / projects / decisions / open questions. Claude inlines it and stops re-introducing. |
| After a decision | `mem_record_decision` | Persists the decision + rationale against a subject. |
| Before asking a familiar question | `mem_recall_decisions` | Retrieves prior decisions on that subject. If any exist, Claude uses them instead of re-asking. |
| Learning anything durable | `mem_remember` | Stores a preference, project, milestone, context fact, or open question. |

The plugin's Stop and PreCompact hooks flush a milestone after every session and before every context compaction, so nothing high-value is lost to `/clear` or window compression. Session ids are whitelisted (`tr -cd 'a-zA-Z0-9_-'`) before any path touch — the shell-injection bug MemPalace had to patch (Issue #110) is fixed by design here.

## Zero-install promise

`pip install gr0m-mem` always produces a working brain. The main branch has exactly one backend:

- **`sqlite_fts`** — SQLite FTS5 BM25 full-text search. Ships with CPython's stdlib `sqlite3` on every mainstream platform. No compiled extras, no embedding model, no Ollama, no network. Lexical-only, but `mem_wakeup` + `mem_record_decision` don't care about the backend — they use their own SQLite table.

Run `gr0m_mem doctor` to verify.

### Want semantic retrieval too?

Switch to the [`semantic`](https://github.com/MichaelAdamGroberman/gr0m_mem/tree/semantic) branch. It adds two more backends with auto-selection:

- **`chromadb`** — HNSW cosine over ChromaDB, best retrieval quality
- **`sqlite_vec`** — pure-Python cosine over SQLite rows, using Ollama for embeddings

Both require either the `chromadb` optional extra or a running Ollama with `mxbai-embed-large` (~1 GB). The semantic branch is a drop-in replacement — same tools, same API, richer retrieval.

## Also in the box

- **Temporal knowledge graph** with mandatory `as_of` filtering. `TemporalEdge` carries `valid_from` / `valid_to`, SQLite persistence with partial indexes on `valid_to IS NULL`, and `active_view()` that refuses to run without an explicit temporal decision. The `FactChecker` runs on every `add_triple` and rejects contradictions in strict mode (the thing MemPalace's `fact_checker.py` advertised but never wired).
- **Per-corpus isolation.** Every corpus is its own FTS5 table — documents from different projects are never mixed. All tools require an explicit `corpus` argument; there is no default tenant.
- **Reproducible benchmarks.** The loop-prevention benchmark (8 scenarios, 15 probes) runs in CI on every push and must stay at 100%. First committed result: [`benchmarks/results/2026-04-08-loop-prevention.json`](benchmarks/results/2026-04-08-loop-prevention.json).

## Install

### As a Claude Code plugin (preferred)

```bash
claude plugin marketplace add MichaelAdamGroberman/gr0m_mem
claude plugin install --scope user gr0m_mem
```

The plugin registers the MCP server plus the Stop / PreCompact hooks in one step.

### From PyPI

```bash
pip install gr0m-mem              # zero-install core (this branch)
pip install "gr0m-mem[tokens]"    # + real tiktoken token counts
```

Then point your MCP client at `python -m gr0m_mem.mcp_server`.

## Quick start

```bash
gr0m_mem doctor
gr0m_mem remember --kind identity --text "Michael, software engineer, macOS"
gr0m_mem remember --kind preference --text "terse responses, no trailing summaries"
gr0m_mem wakeup --tokens 200
```

Now open Claude Code. It calls `mem_wakeup` at session start and sees you before the first message.

## Requirements

- **CPython 3.10, 3.11, or 3.12.** 3.13+ blocked until chromadb and the MCP SDK publish compatible wheels (affects the `semantic` branch; not an issue here).

## License

MIT — see [LICENSE](LICENSE).
