ZacharyZhang-NY
9fe13fffb3
A cartridge used to be an export: materialize it, hash it, and never let it
change behaviour again. The transactive-memory promise needs the opposite —
mounting the home cartridge must make the work cartridge's memories
unfindable, and appending to a cartridge must make a new memory findable
through it.
Cartridge scope (schema v2 -> v3):
- cartridge_atoms (which atoms are in which cartridge) and cartridge_mounts
(which cartridges this machine has mounted now); both rebuilt on reopen,
because a mount is a machine-local state, not a fact about the data.
- mount / switch / unmount / append refuse a cartridge that was built for a
different runtime, naming every differing field instead of a boolean.
- append rewrites atoms.parquet and sparse_index.bm25.zst, recomputes DNA and
the KV fingerprint, and keeps the cartridges row in one SQLite transaction;
the files are written first so a failed export cannot leave a half-cartridge
in the database.
- RetrievalService.search() now ranks inside the mounted scope by default, and
an explicit cartridge_ids filter overrides the mount. Nothing mounted means
the whole library, so an empty store behaves as it did before.
- forget() removes the forgotten atoms from every cartridge's membership:
forgetting must not leave a memory retrievable through a cartridge.
KV fingerprint (kv_fingerprint.py, stored in the manifest):
- model / tokenizer / chat-template hashes, the RoPE block (factor,
original_max_position_embeddings, mrope_interleaved, mrope_section,
partial_rotary_factor), the adapter hash, the context length, the engine
version, and the fingerprint format version.
- A snapshot we cannot read is recorded as unverifiable and listed in
unverifiable_fields; a blind machine refuses to mount rather than pretending
the runtime matches, because a wrong RoPE factor silently corrupts retrieval.
Two defects found by running the new tests, not by reading:
- atoms.parquet could not export a memory at all: pyarrow refuses a struct with
no child field, so metadata={} failed the whole table. The six JSON columns
are now written as JSON text and decoded by the cartridge reader.
- materialize() inserted cartridge membership before the cartridges row existed,
so the foreign key rejected every cartridge.
api.py crossed 500 lines, so the cartridge and mount routes moved to
api_cartridges.py. That module must not use `from __future__ import
annotations`: FastAPI then resolves Depends(settings_dep) against module
globals, where the injected dependency is only a parameter of register(), and
every route starts demanding settings as a query parameter.
Verification: 138 pytest passed (26 new: 10 fingerprint, 16 scope), Go
build/vet/gofmt/test clean, and scripts/mcp_write_smoke.sh now proves the whole
loop across two processes - mount narrows search, a memory written after the
upload is invisible until append_to_cartridge, unmount restores the library,
and rewriting the RoPE factor makes mount_cartridge refuse with "rope: factor:
cartridge 4.0 vs local 2.0". ruff clean on every touched file (the 20 remaining
package errors are in files this change did not touch; HEAD had 25). mypy: one
error, the pre-existing np.savez stub artifact at cartridge_assets.py:329
(HEAD:320). Repo pyright: 62 errors, unchanged from the p0-3 ledger.
Ely-Eye MCP
Ely-Eye MCP exposes a local Context Cartridge memory store as a stdio Model Context Protocol server for coding agents such as Codex and Claude Code.
The server is local-first and read-only against <ely-eye-home>/data/ely_eye.sqlite. It reads Evidence Atoms, cartridge manifests, Memory DNA, proof-suite artifacts, HashHop proofs, and compiled evidence packs. The production database is never modified.
It can be deployed for any .ely_eye store. Identity is anchored on the database file, not on the Ely-Eye repository layout, so the server walks up from the working directory to find .ely_eye/data/ely_eye.sqlite, or takes an explicit --ely-eye-home.
One-command setup
The installer downloads a checksum-verified prebuilt binary for the platform when a tagged release is available, otherwise it builds from source with Go from a repository checkout. Either way it installs the binary into <ely-eye-home>/bin and registers the server with Codex and Claude Code. No Docker.
Windows:
powershell -ExecutionPolicy Bypass -File .\ely-eye-mcp\install.ps1 -Client both
Linux and macOS:
bash ./ely-eye-mcp/install.sh --client both
Force a source build (requires Go 1.25 or newer):
bash ./ely-eye-mcp/install.sh --method source
Codex registration uses codex mcp add. Claude Code project registration writes .mcp.json at the project root; --scope user registers through the Claude CLI instead.
Manual run
From inside a project that owns an .ely_eye store:
go run ./cmd/ely-eye-mcp server
Or point at an explicit store:
go run ./cmd/ely-eye-mcp server --ely-eye-home /path/to/.ely_eye
Tools
ely_eye_status returns atom, source, cartridge, token, and cache-layer counts.
list_cartridges lists local Context Cartridges with manifest JSON and Memory DNA.
get_cartridge reads one cartridge plus artifact metadata, memory capsule index, and asset report.
search_atoms queries the local SQLite FTS index and returns ranked Evidence Atoms.
fetch_atom reads one Evidence Atom by exact id.
compile_context compiles a question into a local evidence pack with the same profile names used by the app (live_demo, extreme_context, library_100m, research_theater).
list_proof_suites lists PRD proof suites under <ely-eye-home>/data/eval_proofs.
list_hashhop_proofs aggregates HashHop and Visual HashHop long-context addressing proofs by kind, hop count, and token budget, with pass counts and example proofs. Proofs are deduplicated by content-derived id.
get_proof_suite reads one PRD proof suite by id, including all checks and a summary of its HashHop proofs.
Resources
ely-eye://project/prd, ely-eye://project/readme, and ely-eye://project/mcp-research expose PRD.md, the project README, and these research notes when those files are present next to the store.
Releases
Pushing a mcp-v* tag runs .github/workflows/mcp-release.yml, which cross-compiles the pure-Go server (CGO disabled) for Linux, macOS, and Windows on amd64 and arm64, then publishes the archives with a SHA256SUMS manifest to a GitHub Release. The installers consume those assets.
Security posture
The server opens SQLite read-only with mode=ro and PRAGMA query_only(1), and uses busy_timeout so reads tolerate concurrent writes by the Ely-Eye app. Tools expose structured outputs and return tool-level errors for invalid inputs so agents self-correct through normal tool calls. Proof ids are validated as single path elements before any filesystem read. The server uses stdio transport for local clients and takes credentials only from the local environment.