mnemohive 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. mnemohive-0.1.4/.gitignore +24 -0
  2. mnemohive-0.1.4/Makefile +57 -0
  3. mnemohive-0.1.4/PKG-INFO +416 -0
  4. mnemohive-0.1.4/PROJECT_SPEC.md +1076 -0
  5. mnemohive-0.1.4/PROJECT_STATUS.md +789 -0
  6. mnemohive-0.1.4/README.md +379 -0
  7. mnemohive-0.1.4/docs/DIRECT_SDK.md +82 -0
  8. mnemohive-0.1.4/docs/MASTER_PLAN.md +1263 -0
  9. mnemohive-0.1.4/docs/MEMORY_SYSTEM_COMPARISON.md +210 -0
  10. mnemohive-0.1.4/docs/MEMORY_TOOL_IMPLEMENTATION_PLAN.md +615 -0
  11. mnemohive-0.1.4/docs/MEMORY_VERSIONING_MVP_RESEARCH.md +410 -0
  12. mnemohive-0.1.4/docs/SQLITE_PLAN.md +548 -0
  13. mnemohive-0.1.4/docs/agent-eval/README.md +406 -0
  14. mnemohive-0.1.4/docs/agent-eval/scenarios.json +374 -0
  15. mnemohive-0.1.4/docs/memory-system-research-sources.json +231 -0
  16. mnemohive-0.1.4/examples/__init__.py +0 -0
  17. mnemohive-0.1.4/examples/agent_undo.py +662 -0
  18. mnemohive-0.1.4/examples/azure_host.py +154 -0
  19. mnemohive-0.1.4/examples/direct_memory.py +149 -0
  20. mnemohive-0.1.4/migrations/.gitkeep +1 -0
  21. mnemohive-0.1.4/migrations/0001_sqlite_init.sql +217 -0
  22. mnemohive-0.1.4/migrations/0002_event_chain.sql +47 -0
  23. mnemohive-0.1.4/migrations/0003_fact_identity.sql +83 -0
  24. mnemohive-0.1.4/migrations/0004_fact_identity_unique.sql +21 -0
  25. mnemohive-0.1.4/mnemo/__init__.py +217 -0
  26. mnemohive-0.1.4/mnemo/chain.py +295 -0
  27. mnemohive-0.1.4/mnemo/cli.py +158 -0
  28. mnemohive-0.1.4/mnemo/config.py +159 -0
  29. mnemohive-0.1.4/mnemo/core.py +1088 -0
  30. mnemohive-0.1.4/mnemo/db.py +156 -0
  31. mnemohive-0.1.4/mnemo/direct.py +834 -0
  32. mnemohive-0.1.4/mnemo/embedder.py +305 -0
  33. mnemohive-0.1.4/mnemo/errors.py +29 -0
  34. mnemohive-0.1.4/mnemo/install.py +779 -0
  35. mnemohive-0.1.4/mnemo/mcp_direct.py +420 -0
  36. mnemohive-0.1.4/mnemo/memory_policy.md +30 -0
  37. mnemohive-0.1.4/mnemo/models.py +288 -0
  38. mnemohive-0.1.4/mnemo/project.py +91 -0
  39. mnemohive-0.1.4/mnemo/seed.py +119 -0
  40. mnemohive-0.1.4/mnemo/services.py +182 -0
  41. mnemohive-0.1.4/mnemo/sqlite.py +400 -0
  42. mnemohive-0.1.4/mnemo/telemetry.py +27 -0
  43. mnemohive-0.1.4/mnemo/transfer.py +362 -0
  44. mnemohive-0.1.4/mnemo/web/__init__.py +0 -0
  45. mnemohive-0.1.4/mnemo/web/app.py +502 -0
  46. mnemohive-0.1.4/mnemo/web/static/app.css +2 -0
  47. mnemohive-0.1.4/mnemo/web/static/htmx.LICENSE +13 -0
  48. mnemohive-0.1.4/mnemo/web/static/htmx.js +3925 -0
  49. mnemohive-0.1.4/mnemo/web/tailwind.config.js +6 -0
  50. mnemohive-0.1.4/mnemo/web/tailwind.css +4 -0
  51. mnemohive-0.1.4/mnemo/web/templates/_macros.html +8 -0
  52. mnemohive-0.1.4/mnemo/web/templates/_rows.html +22 -0
  53. mnemohive-0.1.4/mnemo/web/templates/base.html +40 -0
  54. mnemohive-0.1.4/mnemo/web/templates/diff.html +66 -0
  55. mnemohive-0.1.4/mnemo/web/templates/error.html +8 -0
  56. mnemohive-0.1.4/mnemo/web/templates/fact.html +69 -0
  57. mnemohive-0.1.4/mnemo/web/templates/list.html +31 -0
  58. mnemohive-0.1.4/mnemo/web/templates/retracted.html +45 -0
  59. mnemohive-0.1.4/pyproject.toml +90 -0
  60. mnemohive-0.1.4/scripts/agent_eval.py +790 -0
  61. mnemohive-0.1.4/scripts/check-linux.sh +396 -0
  62. mnemohive-0.1.4/scripts/check-wheel.sh +120 -0
  63. mnemohive-0.1.4/tests/__init__.py +0 -0
  64. mnemohive-0.1.4/tests/conftest.py +114 -0
  65. mnemohive-0.1.4/tests/data/duplicate_set.json +25 -0
  66. mnemohive-0.1.4/tests/data/export_v1_postgres.json +660 -0
  67. mnemohive-0.1.4/tests/data/retrieval_set.json +329 -0
  68. mnemohive-0.1.4/tests/test_agent_eval.py +328 -0
  69. mnemohive-0.1.4/tests/test_agent_undo.py +382 -0
  70. mnemohive-0.1.4/tests/test_azure_pilot.py +291 -0
  71. mnemohive-0.1.4/tests/test_chain.py +389 -0
  72. mnemohive-0.1.4/tests/test_cli.py +91 -0
  73. mnemohive-0.1.4/tests/test_concurrency.py +139 -0
  74. mnemohive-0.1.4/tests/test_config.py +56 -0
  75. mnemohive-0.1.4/tests/test_core.py +170 -0
  76. mnemohive-0.1.4/tests/test_council.py +92 -0
  77. mnemohive-0.1.4/tests/test_demo.py +99 -0
  78. mnemohive-0.1.4/tests/test_diff.py +52 -0
  79. mnemohive-0.1.4/tests/test_direct_mutations.py +658 -0
  80. mnemohive-0.1.4/tests/test_duplicates.py +130 -0
  81. mnemohive-0.1.4/tests/test_embeddings.py +518 -0
  82. mnemohive-0.1.4/tests/test_fact_identity.py +333 -0
  83. mnemohive-0.1.4/tests/test_foundation_integrity.py +142 -0
  84. mnemohive-0.1.4/tests/test_identity.py +267 -0
  85. mnemohive-0.1.4/tests/test_install.py +820 -0
  86. mnemohive-0.1.4/tests/test_lifecycle.py +102 -0
  87. mnemohive-0.1.4/tests/test_mcp_direct_profile.py +137 -0
  88. mnemohive-0.1.4/tests/test_mcp_direct_profile_stdio.py +225 -0
  89. mnemohive-0.1.4/tests/test_mcp_request_ids_stdio.py +112 -0
  90. mnemohive-0.1.4/tests/test_mcp_service_errors_stdio.py +111 -0
  91. mnemohive-0.1.4/tests/test_mcp_shared_scope_stdio.py +193 -0
  92. mnemohive-0.1.4/tests/test_mcp_trust_stdio.py +95 -0
  93. mnemohive-0.1.4/tests/test_packaging.py +31 -0
  94. mnemohive-0.1.4/tests/test_project.py +112 -0
  95. mnemohive-0.1.4/tests/test_retrieval_quality.py +96 -0
  96. mnemohive-0.1.4/tests/test_schema.py +291 -0
  97. mnemohive-0.1.4/tests/test_sdk.py +83 -0
  98. mnemohive-0.1.4/tests/test_search.py +278 -0
  99. mnemohive-0.1.4/tests/test_services.py +181 -0
  100. mnemohive-0.1.4/tests/test_temporal_cache.py +105 -0
  101. mnemohive-0.1.4/tests/test_transfer.py +325 -0
  102. mnemohive-0.1.4/tests/test_trust_features.py +188 -0
  103. mnemohive-0.1.4/tests/test_web.py +628 -0
  104. mnemohive-0.1.4/uv.lock +1686 -0
@@ -0,0 +1,24 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ build/
7
+ dist/
8
+
9
+ # Environments
10
+ .venv/
11
+ venv/
12
+ .env
13
+
14
+ # Tooling caches
15
+ .pytest_cache/
16
+ .ruff_cache/
17
+ .mypy_cache/
18
+ .coverage
19
+ htmlcov/
20
+
21
+ # OS / editor
22
+ .DS_Store
23
+ .idea/
24
+ .vscode/
@@ -0,0 +1,57 @@
1
+ .DEFAULT_GOAL := help
2
+ SHELL := /bin/bash
3
+ RUN := uv run
4
+
5
+ .PHONY: help install migrate seed test lint fmt mcp agents css demo ui export import reindex test-db
6
+
7
+ help: ## Show available targets
8
+ @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
9
+ | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-10s\033[0m %s\n", $$1, $$2}'
10
+
11
+ install: ## Create the venv and install (editable, with dev deps)
12
+ uv sync --locked --extra dev
13
+
14
+ migrate: ## Create the store file if needed and apply migrations/*.sql (MNEMO_DB)
15
+ $(RUN) python -m mnemo.db
16
+
17
+ seed: ## Load demo seed data
18
+ $(RUN) python -m mnemo.seed
19
+
20
+ test: ## Run pytest
21
+ $(RUN) pytest -q
22
+
23
+ lint: ## ruff check + black --check
24
+ $(RUN) ruff check .
25
+ $(RUN) black --check .
26
+
27
+ fmt: ## ruff --fix + black
28
+ $(RUN) ruff check --fix .
29
+ $(RUN) black .
30
+
31
+ mcp: ## Run the seven guarded memory tools over MCP (stdio)
32
+ $(RUN) python -m mnemo.mcp_direct
33
+
34
+ agents: ## Install the mnemo tool from this checkout, then connect the coding agents
35
+ uv tool install --force --reinstall --python 3.12 .
36
+ "$$(uv tool dir --bin)/mnemo" install $(ARGS)
37
+
38
+ demo: ## Direct write -> history -> revert through the SDK, no models
39
+ MNEMO_BACKEND=hash $(RUN) python -m examples.direct_memory
40
+
41
+ export: ## Export the configured scope as versioned JSON (OUT=file, default stdout)
42
+ $(RUN) python -m mnemo.transfer export --out $(or $(OUT),-)
43
+
44
+ import: ## Restore an export (or a Postgres-era one) into an empty store (FILE=export.json)
45
+ $(RUN) python -m mnemo.transfer import $(FILE)
46
+
47
+ reindex: ## Rebuild vectors (for the configured model) and the word index
48
+ $(RUN) mnemo reindex
49
+
50
+ ui: ## Run the FastAPI + HTMX web UI
51
+ $(RUN) uvicorn mnemo.web.app:app --host 127.0.0.1 --port 8000
52
+
53
+ css: ## Rebuild mnemo/web/static/app.css from the templates (needs Node for npx)
54
+ npx -y tailwindcss@3.4.19 -c mnemo/web/tailwind.config.js -i mnemo/web/tailwind.css -o mnemo/web/static/app.css --minify
55
+
56
+ test-db: ## The full suite; every test gets its own temporary store file
57
+ $(RUN) pytest -q
@@ -0,0 +1,416 @@
1
+ Metadata-Version: 2.5
2
+ Name: mnemohive
3
+ Version: 0.1.4
4
+ Summary: One shared, versioned memory for your coding agents (Claude Code, Codex, OpenCode) over MCP, in one local file.
5
+ Project-URL: Homepage, https://github.com/Yugesh-reddy/Mnemo
6
+ Project-URL: Source, https://github.com/Yugesh-reddy/Mnemo
7
+ Project-URL: Issues, https://github.com/Yugesh-reddy/Mnemo/issues
8
+ Project-URL: Changelog, https://github.com/Yugesh-reddy/Mnemo/releases
9
+ License: MIT
10
+ Keywords: claude-code,codex,coding-agents,mcp,memory,opencode,sqlite
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development
20
+ Requires-Python: >=3.12
21
+ Requires-Dist: fastapi>=0.110
22
+ Requires-Dist: fastembed<0.10,>=0.9.1
23
+ Requires-Dist: httpx>=0.27
24
+ Requires-Dist: jinja2>=3.1
25
+ Requires-Dist: mcp<2,>=1.2
26
+ Requires-Dist: pydantic-settings>=2.2
27
+ Requires-Dist: pydantic>=2.6
28
+ Requires-Dist: python-multipart>=0.0.9
29
+ Requires-Dist: sqlite-vec<0.2,>=0.1.9
30
+ Requires-Dist: uvicorn>=0.30
31
+ Provides-Extra: dev
32
+ Requires-Dist: black>=24.0; extra == 'dev'
33
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
34
+ Requires-Dist: pytest>=8.0; extra == 'dev'
35
+ Requires-Dist: ruff>=0.4; extra == 'dev'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # Mnemo
39
+
40
+ **One shared, versioned memory for your coding agents.** Claude Code, Codex, OpenCode
41
+ and other MCP clients on your machine read and write the same memory, for each project and
42
+ across projects. Every change is kept, attributed to the agent that made it, and can
43
+ be undone. Everything runs locally.
44
+
45
+ [![License MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Yugesh-reddy/Mnemo/blob/main/pyproject.toml)
46
+
47
+ ## Quick start
48
+
49
+ You need macOS or Linux with [uv](https://docs.astral.sh/uv/). Nothing else runs: memory
50
+ is one file, `~/.mnemo/mnemo.db`, and the embedding model runs inside Mnemo. On Linux a
51
+ glibc distribution is needed (Debian, Ubuntu and uv's own Python are tested); Alpine
52
+ and other musl systems are not supported, because `sqlite-vec` publishes no wheels for
53
+ them. Windows has not been tested: the code avoids the POSIX assumptions found so far
54
+ (`.exe` server paths, escaped paths in agent configs, UTF-8 files, `path:` project
55
+ names), but nobody has run it there yet.
56
+
57
+ ```bash
58
+ uv tool install mnemohive
59
+ mnemo install # connect Claude Code, Codex and OpenCode (shows every change, asks first)
60
+ ```
61
+
62
+ The package is `mnemohive` on PyPI; the command it installs is `mnemo`.
63
+
64
+ `mnemo install` downloads the embedding model (`BAAI/bge-small-en-v1.5`, about 67 MB,
65
+ from Hugging Face) after you confirm, creates the memory file (readable only by you),
66
+ registers Mnemo with Claude Code and Codex (and OpenCode, when it is installed), and
67
+ adds a short [memory policy](https://github.com/Yugesh-reddy/Mnemo/blob/main/mnemo/memory_policy.md) to their global instructions. The agents run
68
+ the installed tool's own server. Then start a new session in any repository. For
69
+ example, tell Claude Code:
70
+
71
+ > Heads-up: in this repo we run tests with `make test-db`.
72
+
73
+ Later, ask Codex in the same repository:
74
+
75
+ > How do I run the tests here?
76
+
77
+ Codex finds the note in the shared memory and answers `make test-db`.
78
+
79
+ `mnemo uninstall` removes exactly what `mnemo install` added; your memories stay in
80
+ the file.
81
+
82
+ To update, run `uv tool upgrade mnemohive` and then `mnemo install`, which applies
83
+ any new schema migrations and refreshes the agents' configuration. Until then, the
84
+ tools answer with an error that says what to run.
85
+
86
+ **Installed from GitHub before 0.1.3** (the tool was called `mnemo` then): run
87
+ `uv tool uninstall mnemo`, then `uv tool install mnemohive` and `mnemo install`.
88
+ Your memories stay in `~/.mnemo/mnemo.db`.
89
+
90
+ **Upgrading from the Postgres version** (before 0.1.0): the new version does not read
91
+ the Postgres database, so carry your memories over with an export.
92
+
93
+ ```bash
94
+ mnemo-transfer export --all-scopes --out mnemo-postgres.json # old version, Postgres up
95
+ uv tool uninstall mnemo && uv tool install mnemohive
96
+ mnemo import mnemo-postgres.json # creates ~/.mnemo/mnemo.db; same IDs, history, receipts
97
+ mnemo install # embeds the imported memories with the chosen model
98
+ ```
99
+
100
+ Import leaves the vectors to `mnemo install`, which now uses the model inside Mnemo
101
+ by default; add `--backend ollama` to keep using Ollama. Your Postgres data is not changed, and `mnemo up`/`mnemo down` are gone:
102
+ stop the old container with Docker when you no longer need it. To go back, install
103
+ the tag: `uv tool install --force git+https://github.com/Yugesh-reddy/Mnemo@v0.0.1-postgres`.
104
+
105
+ **From a checkout** (to change Mnemo itself): `git clone` it, then `make install`
106
+ and `make agents`. `make agents` installs the tool from your checkout first,
107
+ so the agents keep working if you move or delete it; rerun it after changing code.
108
+
109
+ ## What you get
110
+
111
+ - **Shared across agents.** Every agent reads the same memory. Each one writes under
112
+ its own name (`claude-code`, `codex`), so history shows who changed what.
113
+ - **Project and global scopes.** Memories belong to the git repository the agent is
114
+ working in (SSH and HTTPS clones share them) and stay out of other repositories.
115
+ Things you say apply everywhere, like "always use uv", go to the global scope.
116
+ - **History and undo.** A change never overwrites the past: every revision is kept,
117
+ `memory_history` shows it, and `memory_revert` restores an earlier value as a new
118
+ revision. Stale writes are rejected, and retrying a change doesn't apply it twice.
119
+ - **Clear failures.** If the memory file or the embedding model is missing,
120
+ the agent gets an error that names the command that fixes it, and the server keeps
121
+ running.
122
+ - **Local and private.** Memories stay in one file on your disk, embeddings come from a
123
+ model inside Mnemo (or your Ollama), and nothing is sent anywhere else. There is
124
+ no telemetry.
125
+
126
+ ## Does it work?
127
+
128
+ The [coding-agent eval](https://github.com/Yugesh-reddy/Mnemo/blob/main/docs/agent-eval/README.md) runs sixteen scenarios with the real
129
+ Claude Code and Codex CLIs in throwaway repositories: a convention told to one agent
130
+ and used by the other, an end-of-day handoff, a correction, several values of one
131
+ kind, isolation between projects, a preference for all projects, a restated rule, a
132
+ retracted memory, small talk, a question nothing answers, and five poisoning attempts
133
+ (instructions planted in repository files, in a code comment aimed at the user's other
134
+ projects, and inside a stored memory). Without
135
+ instructions, Codex never saved what it was told, and the first ten scenarios passed
136
+ **4 of 10**. With the memory policy that `mnemo install` installs, all twelve passed
137
+ (**12 of 12**), including with Claude Code's own auto-memory left on. On the
138
+ single-file store the same setup passed 12 of 12 in three more runs, one with Ollama
139
+ and two with the model inside Mnemo, with no Mnemo tool errors. After a policy change
140
+ for the three harder poisoning scenarios (tell the user about planted instructions;
141
+ retract a poisoned memory unasked), all sixteen passed (**16 of 16**, with a control
142
+ that a plain memory is still used). Each scenario ran once
143
+ per run on tiny planted repositories, so this shows the approach works, not how often it works in long, real sessions.
144
+
145
+ ## How agents use it
146
+
147
+ Seven MCP tools, served by `mnemo-mcp-direct`:
148
+
149
+ | Tool | Contract |
150
+ |---|---|
151
+ | `memory_create` | Save a new memory in the project (default) or global scope, with its `source`: `user` (high trust), `tool` (medium) or `agent` (low, the default). Trust is what the writing agent claims; the recorded actor, the history and retract are the defence when an agent is wrong or misled. An existing subject/predicate in that scope returns `ALREADY_EXISTS` with its ID. |
152
+ | `memory_get` | Read the current value and event ID, or a full historical value and whether it can be restored. |
153
+ | `memory_search` | Search the project and global scopes; hits carry fact ID, event ID, scope, who wrote the value (`actor`), when (`recorded_at`) and its `provenance` and `trust_level`. |
154
+ | `memory_update` | Change a memory by fact ID, passing the event ID you read as `expected_event_id`, with its `source`. |
155
+ | `memory_history` | Page through revisions, newest first, with value previews. |
156
+ | `memory_revert` | Copy a historical value into a new revision, keeping its provenance and trust. |
157
+ | `memory_retract` | Withdraw a wrong or planted memory, including one just created: it leaves search and `memory_get` reports `status: "retracted"`. History is kept; revert or update restores it. |
158
+
159
+ Agents read before changing a memory, pass the revision they read, re-read on a
160
+ conflict, and ask which change to undo when "undo that" is ambiguous. `request_id` is
161
+ optional; sending the same one again replays the original result instead of
162
+ applying the change twice. Errors are JSON `{code, message, details}` with MCP's
163
+ `isError` flag set:
164
+
165
+ | Code | What to do |
166
+ |---|---|
167
+ | `INVALID_INPUT` | Correct the input, ID, value size, limit, or cursor. |
168
+ | `NOT_FOUND` | Check the memory ID; memories from other projects are not visible. |
169
+ | `ALREADY_EXISTS` | Read the returned fact ID, then use a guarded update. |
170
+ | `REVISION_CONFLICT` | Re-read and reconsider; the memory changed since you read it. |
171
+ | `INVALID_RESTORE_TARGET` | Select a revision belonging to this memory. |
172
+ | `UNSUPPORTED_STATE` | This current state or historical revision cannot be restored here. |
173
+ | `REQUEST_ID_REUSED` | A request ID was reused with different parameters; retry the original or leave it out. |
174
+ | `UNSUPPORTED_OPERATION` | Undoing a creation is not supported. |
175
+ | `SERVICE_UNAVAILABLE` | The memory file or the embedding service is missing, not set up, or busy; the message names the fix. |
176
+
177
+ ## Configuration
178
+
179
+ Settings come from `MNEMO_*` environment variables or `.env`; see
180
+ [.env.example](https://github.com/Yugesh-reddy/Mnemo/blob/main/.env.example). The ones that matter most:
181
+
182
+ | Setting | Default | Meaning |
183
+ |---|---|---|
184
+ | `MNEMO_DB` | `~/.mnemo/mnemo.db` | The memory file every agent shares. Keep it on a local disk, not in a synced folder. |
185
+ | `MNEMO_BACKEND` | `local` | Embeddings: `local` (a model inside Mnemo, no server; see below), `ollama` (a local Ollama server), `hash` (no model, matches exact words only) or `openai` (sends text to OpenAI). |
186
+ | `MNEMO_ACTOR` | the agent ID | Who is writing; set per agent by `mnemo install`. |
187
+ | `MNEMO_PROJECT` | detected | Overrides the project detected from the git repository. |
188
+ | `MNEMO_NAMESPACE`, `MNEMO_USER_ID` | `default` | Shared by every agent that should see the same memory. |
189
+
190
+ `mnemo install` options: `--dry-run` shows the changes only,
191
+ `--agent claude|codex|opencode` limits them to the agents named, `--codex-home` points
192
+ at another Codex home (a `codex` wrapper that pins one is detected), `--opencode-dir`
193
+ at another OpenCode config directory, `--backend ollama` uses Ollama's
194
+ `nomic-embed-text` instead of the model inside Mnemo, and `--claude-auto-memory off` also turns off Claude Code's built-in memory.
195
+
196
+ OpenCode gets a `mnemo` server under `mcp` in `~/.config/opencode/opencode.json`
197
+ (under `mcp.servers` when the file already groups its servers there, the newer
198
+ layout). An `opencode.jsonc` with comments is never rewritten: the installer prints
199
+ the entry to paste instead, and when OpenCode was only detected, not named with
200
+ `--agent`, it sets up the other agents and skips OpenCode. The policy goes into `~/.config/opencode/AGENTS.md`, or into
201
+ `~/.claude/CLAUDE.md` when OpenCode is reading that file because it has no
202
+ `AGENTS.md` of its own (creating one would stop it reading CLAUDE.md).
203
+
204
+ **The default `local` backend** runs the embedding model inside each Mnemo server.
205
+ `mnemo install` downloads `BAAI/bge-small-en-v1.5` (about 67 MB, from Hugging Face)
206
+ into `~/.mnemo/models`; nothing is downloaded later. Each agent session's server uses
207
+ about 300 MB of memory once it has searched or written (about 60 MB before), and its
208
+ first search takes about 2 s while the model loads. After 5 minutes without a search or
209
+ write the server lets the model go (`MNEMO_LOCAL_MODEL_IDLE_SECONDS`, 0 to keep it):
210
+ on Linux that gives back about 90 MB per idle session; macOS reclaims the memory
211
+ gradually; the next call reloads it in about 0.1 s. On a 28-question check it found
212
+ memories about as well as Ollama (see `tests/test_retrieval_quality.py`), but an
213
+ unrelated question returns a memory more often (3 of 8 questions against 1); the
214
+ model is English-only. `--backend ollama` uses Ollama's `nomic-embed-text` instead
215
+ (about 70 MB per server plus Ollama). Each vector is stored with the model that made it, and search compares
216
+ a question only with vectors from the same model, so switching models keeps your
217
+ memories: `mnemo install` embeds them again with the new model. `mnemo reindex` does
218
+ it by hand with the backend in your shell's `MNEMO_BACKEND`, so set the one the agents
219
+ use. Until then memories are still found by their words.
220
+
221
+ ### Configure by hand
222
+
223
+ With the tool installed, the server is `mnemo-mcp-direct` in `uv tool dir --bin`
224
+ (usually `~/.local/bin`); use its absolute path. The server never downloads the
225
+ model: let `mnemo install` fetch it once, or use `MNEMO_BACKEND=ollama` with
226
+ `MNEMO_EMBED_DIM=768`. Claude Code, once for every repository:
227
+
228
+ ```bash
229
+ claude mcp add mnemo --scope user \
230
+ -e MNEMO_BACKEND=local -e MNEMO_MODEL_DIR=/Users/you/.mnemo/models \
231
+ -e MNEMO_ACTOR=claude-code \
232
+ -- /Users/you/.local/bin/mnemo-mcp-direct
233
+ ```
234
+
235
+ Codex, in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`):
236
+
237
+ ```toml
238
+ [mcp_servers.mnemo]
239
+ command = "/Users/you/.local/bin/mnemo-mcp-direct"
240
+ default_tools_approval_mode = "approve" # lets `codex exec` call the tools unattended
241
+
242
+ [mcp_servers.mnemo.env]
243
+ MNEMO_BACKEND = "local"
244
+ MNEMO_MODEL_DIR = "/Users/you/.mnemo/models"
245
+ MNEMO_ACTOR = "codex"
246
+ ```
247
+
248
+ OpenCode, in `~/.config/opencode/opencode.json`:
249
+
250
+ ```json
251
+ {
252
+ "mcp": {
253
+ "mnemo": {
254
+ "type": "local",
255
+ "command": ["/Users/you/.local/bin/mnemo-mcp-direct"],
256
+ "environment": {"MNEMO_BACKEND": "local", "MNEMO_ACTOR": "opencode"}
257
+ }
258
+ }
259
+ }
260
+ ```
261
+
262
+ Also paste [the memory policy](https://github.com/Yugesh-reddy/Mnemo/blob/main/mnemo/memory_policy.md) into `~/.claude/CLAUDE.md`,
263
+ `$CODEX_HOME/AGENTS.md` and OpenCode's rules file: without it, Codex did not save
264
+ anything in the eval. Other
265
+ clients such as Claude Desktop or [Cursor](https://cursor.com/docs/mcp) take the same
266
+ command and environment in their JSON configuration (Cursor also needs
267
+ `"type": "stdio"`). They are not started inside a repository, so they see only the
268
+ global scope unless you set `MNEMO_PROJECT`. In a checkout, `make mcp` runs
269
+ the server from source.
270
+
271
+ ## What Mnemo depends on
272
+
273
+ | Service | Used for | If it is down |
274
+ |---|---|---|
275
+ | One SQLite file (`~/.mnemo/mnemo.db`) with [sqlite-vec](https://github.com/asg017/sqlite-vec) | All memories, history and receipts | Tools return `SERVICE_UNAVAILABLE` naming the fix (`mnemo install`) |
276
+ | The embedding model in `~/.mnemo/models` (or Ollama with `nomic-embed-text`) | Embeddings for search and writes | Search and writes fail with the fix; reading by ID, history and revert still work |
277
+ | git | Detecting the project | Only the global scope is available |
278
+
279
+ No language model runs inside Mnemo for this path: the agent decides what to save.
280
+ The optional web UI serves its own copies of Tailwind's CSS and htmx, so it works offline.
281
+
282
+ ## What the store guarantees
283
+
284
+ | Mechanism | Where it lives |
285
+ |---|---|
286
+ | Triggers reject changes to event payloads and receipts, deletes, and `INSERT OR REPLACE`; supersession and recall bookkeeping remain mutable. | [Schema](https://github.com/Yugesh-reddy/Mnemo/blob/main/migrations/0001_sqlite_init.sql) |
287
+ | Every write takes the file's single write lock; expected-event guards reject stale updates/reverts, including A→B→A. Eight processes racing one update give one winner. | [Direct API](https://github.com/Yugesh-reddy/Mnemo/blob/main/mnemo/direct.py), [race tests](https://github.com/Yugesh-reddy/Mnemo/blob/main/tests/test_concurrency.py) |
288
+ | Each event is chained to the previous one by a SHA-256 hash; `mnemo verify` recomputes the chain and reports any event changed, removed or inserted outside Mnemo. It records the head it verified beside the store (`mnemo.db.verified`, or `--witness FILE`) and next time checks the chain still passes through it, which catches a rewrite of every later hash too. A memory's scope, subject and key cannot be changed or deleted through SQL either, and are sealed the same way, so `mnemo verify` also reports a memory moved or renamed around the triggers. After restoring a backup on purpose, delete that file and verify again. | [Chain](https://github.com/Yugesh-reddy/Mnemo/blob/main/mnemo/chain.py), [spec §27](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md#27-tamper-evidence--november-19-2026), [§31](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md#31-a-memorys-identity-is-permanent--november-20-2026) |
289
+ | Event, HEAD, and append-only receipt commit together. Receipts survive restarts and remain for the store's lifetime. | [Schema](https://github.com/Yugesh-reddy/Mnemo/blob/main/migrations/0001_sqlite_init.sql) |
290
+ | Revert copies source payload, embedding and lineage into a new event; it does not raise source trust. | [Core](https://github.com/Yugesh-reddy/Mnemo/blob/main/mnemo/core.py), [direct contract](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md#15-additive-guarded-memory-contract--september-22-2026) |
291
+ | Historical reads distinguish recording time (`as_of`) from world validity (`valid_at`). Archive is reversible; `blame`, `diff`, and `commit` expose history. | [Temporal contract](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md#14-correctness-amendment--september-9-2026) |
292
+
293
+ To see the versioning without any agent or model, run `make demo` in a
294
+ checkout. It
295
+ remembers PostgreSQL, changes it to MySQL, rejects a stale update, inspects history
296
+ and restores PostgreSQL; retrying the restore returns its receipt:
297
+
298
+ ```text
299
+ ADD(PostgreSQL) -> UPDATE(MySQL) -> REVERT(PostgreSQL)
300
+ Source trust preserved: agent_inference / low
301
+ ```
302
+
303
+ The demo uses the `hash` backend in a temporary file, so it never touches your
304
+ memories.
305
+
306
+ The [Python guide](https://github.com/Yugesh-reddy/Mnemo/blob/main/docs/DIRECT_SDK.md) shows `Mnemo.direct` and the async
307
+ `DirectMemory(store)` interface. Existing `add`, `search`, `blame`, `revert`,
308
+ `diff`, `log` and `commit` APIs remain available with their legacy
309
+ contracts. Legacy `add` performs alias deduplication; direct updates preserve
310
+ exact spelling changes. Legacy human-review revert is not revision-guarded.
311
+
312
+ ### Back up or move a store
313
+
314
+ ```bash
315
+ mnemo export --out mnemo-export.json # the configured scope; stdout without --out
316
+ mnemo export --all-scopes --out all.json # every scope
317
+ mnemo import mnemo-export.json # into an empty store only
318
+ ```
319
+
320
+ Copying `~/.mnemo/mnemo.db` while no agent is running also works. The export is one
321
+ versioned JSON document: facts with their HEADs, every event, commits, receipts and
322
+ the applied migrations, exactly as stored. Vectors are left out and rebuilt on
323
+ import with the destination's model. Import restores the rows in one transaction,
324
+ reads back what it wrote and rolls back if anything differs, so IDs, sequence
325
+ numbers, history and receipt replays come through unchanged. It also reads exports
326
+ from the Postgres version ([spec §16](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md#16-exportimport--september-22-2026)).
327
+
328
+ ## Review memory in the browser
329
+
330
+ ```bash
331
+ make ui # installed as a tool: mnemo ui
332
+ # then open http://127.0.0.1:8000
333
+ ```
334
+
335
+ The page opens on the global memories; the **Scope** menu in the header lists every
336
+ project that has memories in the store, and the choice stays in the address
337
+ (`?scope=…`) on every page. A correction or restore always applies to the scope the
338
+ memory belongs to.
339
+
340
+ A project's scope is `<MNEMO_NAMESPACE>@<project>`, where the project is the
341
+ repository's remote in lower case (for example `github.com/you/your-repo`), or
342
+ `path:<repository path>` when it has no remote. The UI needs the same embedding
343
+ backend as the agents (the model inside Mnemo by default). Search → open history → revert a
344
+ revision. A stale form
345
+ returns HTTP 409, shows the latest state, and writes nothing. Repeated submissions
346
+ replay their receipt. Unrestorable revisions have no restore button. **Retracted**
347
+ lists every memory an agent withdrew, with who did it, when and why, so you can
348
+ restore one an agent was misled into retracting. **Manual
349
+ correction** records a value you checked yourself as human review (high trust). It is
350
+ guarded like restore: if an agent changed the memory while the page was open, the
351
+ correction is refused with HTTP 409 and the page shows the agent's value.
352
+
353
+ ## Checks, layout and limits
354
+
355
+ ```bash
356
+ make test # every test gets its own temporary memory file
357
+ make lint
358
+ uv build
359
+ bash scripts/check-wheel.sh
360
+ ```
361
+
362
+ The packaging check uses a fresh environment and exercises installed SDK/MCP
363
+ behavior. The [correctness workflow](https://github.com/Yugesh-reddy/Mnemo/blob/main/.github/workflows/correctness.yml)
364
+ runs the tests on macOS and Linux. `bash scripts/check-linux.sh` (Docker) installs the
365
+ wheel as a new user would in a fresh Linux container: `mnemo install` with and without
366
+ agents present, the MCP server over stdio, `mnemo verify`, the web UI and
367
+ `mnemo uninstall`; `--local` also downloads the embedding model. Optional live-Ollama
368
+ tests skip when their models are unavailable.
369
+
370
+ `mnemo/` contains the async store, direct API, SDK, MCP server and installer;
371
+ `mnemo/web/` the review UI; `migrations/` holds the schema; `examples/`, `scripts/`
372
+ and `tests/` hold the demos, the agent eval and checks.
373
+ [The spec](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_SPEC.md) defines contracts; [the plan](https://github.com/Yugesh-reddy/Mnemo/blob/main/docs/MASTER_PLAN.md) and
374
+ [status](https://github.com/Yugesh-reddy/Mnemo/blob/main/PROJECT_STATUS.md) track delivery.
375
+
376
+ This is a local, single-user service. Scope columns do not provide authentication
377
+ or access control, and memories are stored unencrypted, so don't save secrets.
378
+ Identity is one current value per subject/predicate in a scope. Direct mutations
379
+ accept strings up to 8192 UTF-8 bytes and operate on active, durable, non-expiring
380
+ memories, or retracted ones. Grouped undo, branching, merging and multi-user access
381
+ are out of scope for now.
382
+
383
+ ## Architecture
384
+
385
+ ```mermaid
386
+ flowchart LR
387
+ Claude[Claude Code] --> Direct[Seven direct MCP tools]
388
+ Codex[Codex] --> Direct
389
+ OpenCode[OpenCode] --> Direct
390
+ UI[Web revert] --> Direct
391
+ Direct --> Core[Scoped event store]
392
+ Core --> Events[Append-only events]
393
+ Core --> Heads[Current HEADs]
394
+ Direct --> Receipts[Durable mutation receipts]
395
+ Events --> History[History / as-of reads / diff]
396
+ ```
397
+
398
+ ## History: the automatic extraction pipeline (archived)
399
+
400
+ Mnemo began as a write-quality pipeline: it recorded conversation turns, and a worker
401
+ extracted facts, checked them against their source, deduplicated, scored and tiered
402
+ them. Coding agents save what matters themselves, and small local models did not
403
+ reach the quality target, so the pipeline, its evals and its evidence were removed
404
+ from `main`. They remain at the git tag `archive/extraction-pipeline`
405
+ (`git checkout archive/extraction-pipeline`), on the Postgres version of the store.
406
+
407
+ An earlier [host-agent pilot](https://github.com/Yugesh-reddy/Mnemo/blob/main/docs/direct-pilot/README.md) let Qwen or Azure Luna
408
+ drive the direct tools, one attempt per scenario: both reached the intended end state
409
+ in 5/6 scenarios, and on an ambiguous "undo that" Luna reverted both memories
410
+ instead of asking. The revision guards block stale and racing writes but cannot know
411
+ whether a write was wanted; what they guarantee is that such a change is attributed,
412
+ visible in history and reversible.
413
+
414
+ ## License
415
+
416
+ The project declares the **MIT license** in [pyproject.toml](https://github.com/Yugesh-reddy/Mnemo/blob/main/pyproject.toml).