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.
- mnemohive-0.1.4/.gitignore +24 -0
- mnemohive-0.1.4/Makefile +57 -0
- mnemohive-0.1.4/PKG-INFO +416 -0
- mnemohive-0.1.4/PROJECT_SPEC.md +1076 -0
- mnemohive-0.1.4/PROJECT_STATUS.md +789 -0
- mnemohive-0.1.4/README.md +379 -0
- mnemohive-0.1.4/docs/DIRECT_SDK.md +82 -0
- mnemohive-0.1.4/docs/MASTER_PLAN.md +1263 -0
- mnemohive-0.1.4/docs/MEMORY_SYSTEM_COMPARISON.md +210 -0
- mnemohive-0.1.4/docs/MEMORY_TOOL_IMPLEMENTATION_PLAN.md +615 -0
- mnemohive-0.1.4/docs/MEMORY_VERSIONING_MVP_RESEARCH.md +410 -0
- mnemohive-0.1.4/docs/SQLITE_PLAN.md +548 -0
- mnemohive-0.1.4/docs/agent-eval/README.md +406 -0
- mnemohive-0.1.4/docs/agent-eval/scenarios.json +374 -0
- mnemohive-0.1.4/docs/memory-system-research-sources.json +231 -0
- mnemohive-0.1.4/examples/__init__.py +0 -0
- mnemohive-0.1.4/examples/agent_undo.py +662 -0
- mnemohive-0.1.4/examples/azure_host.py +154 -0
- mnemohive-0.1.4/examples/direct_memory.py +149 -0
- mnemohive-0.1.4/migrations/.gitkeep +1 -0
- mnemohive-0.1.4/migrations/0001_sqlite_init.sql +217 -0
- mnemohive-0.1.4/migrations/0002_event_chain.sql +47 -0
- mnemohive-0.1.4/migrations/0003_fact_identity.sql +83 -0
- mnemohive-0.1.4/migrations/0004_fact_identity_unique.sql +21 -0
- mnemohive-0.1.4/mnemo/__init__.py +217 -0
- mnemohive-0.1.4/mnemo/chain.py +295 -0
- mnemohive-0.1.4/mnemo/cli.py +158 -0
- mnemohive-0.1.4/mnemo/config.py +159 -0
- mnemohive-0.1.4/mnemo/core.py +1088 -0
- mnemohive-0.1.4/mnemo/db.py +156 -0
- mnemohive-0.1.4/mnemo/direct.py +834 -0
- mnemohive-0.1.4/mnemo/embedder.py +305 -0
- mnemohive-0.1.4/mnemo/errors.py +29 -0
- mnemohive-0.1.4/mnemo/install.py +779 -0
- mnemohive-0.1.4/mnemo/mcp_direct.py +420 -0
- mnemohive-0.1.4/mnemo/memory_policy.md +30 -0
- mnemohive-0.1.4/mnemo/models.py +288 -0
- mnemohive-0.1.4/mnemo/project.py +91 -0
- mnemohive-0.1.4/mnemo/seed.py +119 -0
- mnemohive-0.1.4/mnemo/services.py +182 -0
- mnemohive-0.1.4/mnemo/sqlite.py +400 -0
- mnemohive-0.1.4/mnemo/telemetry.py +27 -0
- mnemohive-0.1.4/mnemo/transfer.py +362 -0
- mnemohive-0.1.4/mnemo/web/__init__.py +0 -0
- mnemohive-0.1.4/mnemo/web/app.py +502 -0
- mnemohive-0.1.4/mnemo/web/static/app.css +2 -0
- mnemohive-0.1.4/mnemo/web/static/htmx.LICENSE +13 -0
- mnemohive-0.1.4/mnemo/web/static/htmx.js +3925 -0
- mnemohive-0.1.4/mnemo/web/tailwind.config.js +6 -0
- mnemohive-0.1.4/mnemo/web/tailwind.css +4 -0
- mnemohive-0.1.4/mnemo/web/templates/_macros.html +8 -0
- mnemohive-0.1.4/mnemo/web/templates/_rows.html +22 -0
- mnemohive-0.1.4/mnemo/web/templates/base.html +40 -0
- mnemohive-0.1.4/mnemo/web/templates/diff.html +66 -0
- mnemohive-0.1.4/mnemo/web/templates/error.html +8 -0
- mnemohive-0.1.4/mnemo/web/templates/fact.html +69 -0
- mnemohive-0.1.4/mnemo/web/templates/list.html +31 -0
- mnemohive-0.1.4/mnemo/web/templates/retracted.html +45 -0
- mnemohive-0.1.4/pyproject.toml +90 -0
- mnemohive-0.1.4/scripts/agent_eval.py +790 -0
- mnemohive-0.1.4/scripts/check-linux.sh +396 -0
- mnemohive-0.1.4/scripts/check-wheel.sh +120 -0
- mnemohive-0.1.4/tests/__init__.py +0 -0
- mnemohive-0.1.4/tests/conftest.py +114 -0
- mnemohive-0.1.4/tests/data/duplicate_set.json +25 -0
- mnemohive-0.1.4/tests/data/export_v1_postgres.json +660 -0
- mnemohive-0.1.4/tests/data/retrieval_set.json +329 -0
- mnemohive-0.1.4/tests/test_agent_eval.py +328 -0
- mnemohive-0.1.4/tests/test_agent_undo.py +382 -0
- mnemohive-0.1.4/tests/test_azure_pilot.py +291 -0
- mnemohive-0.1.4/tests/test_chain.py +389 -0
- mnemohive-0.1.4/tests/test_cli.py +91 -0
- mnemohive-0.1.4/tests/test_concurrency.py +139 -0
- mnemohive-0.1.4/tests/test_config.py +56 -0
- mnemohive-0.1.4/tests/test_core.py +170 -0
- mnemohive-0.1.4/tests/test_council.py +92 -0
- mnemohive-0.1.4/tests/test_demo.py +99 -0
- mnemohive-0.1.4/tests/test_diff.py +52 -0
- mnemohive-0.1.4/tests/test_direct_mutations.py +658 -0
- mnemohive-0.1.4/tests/test_duplicates.py +130 -0
- mnemohive-0.1.4/tests/test_embeddings.py +518 -0
- mnemohive-0.1.4/tests/test_fact_identity.py +333 -0
- mnemohive-0.1.4/tests/test_foundation_integrity.py +142 -0
- mnemohive-0.1.4/tests/test_identity.py +267 -0
- mnemohive-0.1.4/tests/test_install.py +820 -0
- mnemohive-0.1.4/tests/test_lifecycle.py +102 -0
- mnemohive-0.1.4/tests/test_mcp_direct_profile.py +137 -0
- mnemohive-0.1.4/tests/test_mcp_direct_profile_stdio.py +225 -0
- mnemohive-0.1.4/tests/test_mcp_request_ids_stdio.py +112 -0
- mnemohive-0.1.4/tests/test_mcp_service_errors_stdio.py +111 -0
- mnemohive-0.1.4/tests/test_mcp_shared_scope_stdio.py +193 -0
- mnemohive-0.1.4/tests/test_mcp_trust_stdio.py +95 -0
- mnemohive-0.1.4/tests/test_packaging.py +31 -0
- mnemohive-0.1.4/tests/test_project.py +112 -0
- mnemohive-0.1.4/tests/test_retrieval_quality.py +96 -0
- mnemohive-0.1.4/tests/test_schema.py +291 -0
- mnemohive-0.1.4/tests/test_sdk.py +83 -0
- mnemohive-0.1.4/tests/test_search.py +278 -0
- mnemohive-0.1.4/tests/test_services.py +181 -0
- mnemohive-0.1.4/tests/test_temporal_cache.py +105 -0
- mnemohive-0.1.4/tests/test_transfer.py +325 -0
- mnemohive-0.1.4/tests/test_trust_features.py +188 -0
- mnemohive-0.1.4/tests/test_web.py +628 -0
- 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/
|
mnemohive-0.1.4/Makefile
ADDED
|
@@ -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
|
mnemohive-0.1.4/PKG-INFO
ADDED
|
@@ -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
|
+
[](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).
|