Project Info
What it is Perseus Vault Codex is an MCP server that gives any OpenAI Codex agent persistent, encrypted, local-first memory. Install it and Codex gains five memory tools — perseus_remember, perseus_recall, perseus_forget, perseus_reflect, perseus_status — so it remembers your project's conventions, past decisions, and debugging context across every session. Under the hood it wraps Perseus Vault: a single 12 MB binary, fully local, AES-256-GCM encrypted at rest, with FTS5 keyword + hybrid recall and no API keys, no cloud dependency, and no telemetry.
Inspiration
Every Codex session starts from zero. The agent re-learns your build commands, re-discovers your conventions, and re-derives the same architectural context you explained an hour ago. Memory is the missing primitive for coding agents — and the existing memory stores don't fit a developer's machine. mem0 is cloud-dependent, cognee is Python-only with no encryption at rest, Letta doesn't encrypt local storage, and Chroma is a vector DB rather than structured agent memory. None are single-binary, zero-infra, and encrypted. Developer memory — your unreleased code, your architecture, your secrets-adjacent context — is exactly the kind of data that should never leave the machine unencrypted. So we built the local, encrypted answer and wired it natively into Codex.
What it does
Remembers across sessions. perseus_remember stores a fact, decision, convention, or gotcha, keyed so re-learning updates rather than duplicates. Recalls on demand. perseus_recall retrieves relevant context with FTS5 keyword + hybrid ranking. A new session picks up exactly where the last left off. Forgets cleanly. perseus_forget soft-deletes stale or wrong memories (recoverable). Reflects. perseus_reflect gathers grounding memories and uses your OpenAI/GPT-5.6 key to synthesize a cited insight — and degrades gracefully to returning the assembled context when no LLM is configured. Reports. perseus_status shows memory count, that encryption is active, and where the local DB lives. Zero config: on first run it auto-creates an encrypted vault at ~/.perseus-vault/codex/memory.db and generates the AES-256-GCM key itself. One command wires it into Codex: perseus-vault-codex-setup.
How we built it
— and how Codex + GPT-5.6 were used Codex was used as an implementation and verification partner during Build Week. This final review session does not claim authorship of the pre-existing core; it read the complete implementation and test suite, then independently exercised and hardened it. Reviewed the real integration. Codex traced the Codex-facing JSON-RPC server, five-verb translation layer, zero-config setup, and the vendored client that starts the perseus-vault subprocess. Verified, rather than assumed. It ran all 32 tests against perseus-vault 2.17.0, ran the two-session demo, and confirmed a memory saved before a complete client teardown was recalled by a new client. Checked encryption at rest directly. It wrote a unique marker to the default ~/.perseus-vault/codex/memory.db, read the database as raw bytes, and confirmed that marker was absent before soft-deleting the audit memory. Hardened a transport edge case. On an unexpected vault stdout EOF, the client now tears down its unusable subprocess before raising. A regression test confirms the next call can auto-respawn instead of repeatedly receiving EOF. Measured and challenged the benchmarks. Codex ran the real encrypted-vault benchmarks and documented their limits: latency/recall numbers apply to the supplied synthetic workload; the token-savings percentage is scenario modeling, not a universal observed outcome. perseus_reflect can use the user's configured OpenAI-compatible model to synthesize recalled memories; it falls back to inspectable context when no LLM endpoint is configured. Built with: Python (zero runtime deps), the Model Context Protocol (JSON-RPC 2.0 over stdio), Perseus Vault (Rust single binary, SQLite + FTS5, AES-256-GCM), OpenAI Codex, GPT-5.6.
Challenges we ran into
stdout is the protocol. In an MCP stdio server, a single stray print to stdout corrupts the JSON-RPC stream. We routed all logging to stderr and added tests that drive the full serve() loop over fake streams to catch regressions. Not blocking Codex at startup. Codex calls tools/list during startup; if we spawned the vault binary eagerly, a missing binary would hang the session. We made the vault start lazily on the first real tool call. Graceful LLM degradation. When the reflect LLM call fails, the vault returns an error as an ordinary text block. We detect that and fall back to context-only mode instead of surfacing an error string as an "answer." Collapsing 55+ tools to 5. The hard product call was restraint — a coding agent shouldn't reason about 55 memory tools. Choosing the right five verbs was the design. Accomplishments we're proud of One pip install + one setup command + zero config = a Codex agent with encrypted persistent memory. Encryption at rest, on by default, proven by a test that asserts memory plaintext never appears in the on-disk database. Zero runtime Python dependencies — the whole wrapper is self-contained. A real, non-trivial MCP integration with a 31-test suite, verified end-to-end against the real Perseus Vault binary. Measured benchmarks, not claims benchmarks/): recall at p50 8 ms / 5-of-5 recall@10 on a 10k-memory corpus, and a 72.5% context-token reduction over a 30-session horizon vs. re-priming each session — every figure measured against the real binary or labeled as a stated assumption.
What's next
Auto-recall hooks so Codex pulls relevant memory into context without an explicit call. Team memory: shared encrypted vaults synced via the Vault's export/import. Publishing to the OpenAI MCP server registry.
Perseus Vault Codex
Persistent, encrypted, local-first memory for OpenAI Codex agents.
Codex never forgets. Perseus Vault gives your Codex agent persistent encrypted memory — so it remembers your project conventions, past decisions, and debugging context across every session.
License: MIT | Built for OpenAI Build Week — Developer Tools track
The problem
Every Codex session starts from zero. The agent re-learns your build commands, re-discovers your conventions, and re-derives the same architectural context you explained yesterday. Memory is the missing primitive for coding agents.
Existing memory stores don't fit a developer's machine: mem0 is cloud-dependent, cognee is Python-only with no encryption at rest, Letta manages memory but doesn't encrypt local storage, Chroma is a vector DB, not structured agent memory. None are single-binary, zero-infra, and encrypted.
The answer
perseus-vault-codex is a tiny MCP server that wraps Perseus Vault
— a single 12 MB binary, fully local, AES-256-GCM encrypted at rest, with
FTS5 keyword + hybrid recall and no API keys, no cloud, no telemetry. Install
it and any Codex session gains five memory tools:
| Tool | What it does |
|---|---|
perseus_remember | Save a fact, decision, convention, or gotcha across sessions. |
perseus_recall | Retrieve relevant past context (FTS5 + hybrid ranking). |
perseus_forget | Remove a stale or wrong memory. |
perseus_reflect | Synthesize an insight from stored memories (RAG via your OpenAI/GPT-5.6 key). |
perseus_status | Store health: memory count, encryption state, DB location. |
Install
# 1. Install the wrapper (zero Python dependencies)
pip install perseus-vault-codex # from PyPI, or from source (below)
# 2. Install the Perseus Vault binary (single static binary, no deps) and put it on PATH
# https://github.com/Perseus-Computing-LLC/perseus-vault/releases
# 3. Register it with Codex (non-destructive; backs up your config)
perseus-vault-codex-setup
Install from source (works today, before the PyPI release):
git clone https://github.com/Perseus-Computing-LLC/perseus-vault-codex
cd perseus-vault-codex
pip install -e .
perseus-vault-codex-setup
That's it. On first run the server auto-creates an encrypted vault at
~/.perseus-vault/codex/memory.db — no config required.
Configure in Codex
perseus-vault-codex-setup writes this into ~/.codex/config.toml:
[mcp_servers.perseus-vault]
command = "perseus-vault-codex"
args = []
Restart Codex (or start a new session) and the five perseus_* tools are
available. To enable perseus_reflect synthesis, expose your OpenAI key:
[mcp_servers.perseus-vault.env]
OPENAI_API_KEY = "sk-..."
OPENAI_MODEL = "gpt-5.6"
See examples/codex_config.toml for every option.
Example usage
Inside a Codex session:
you> Set up the project. First, check what you already know.
codex> [calls perseus_recall {"query": "project build and test conventions"}]
I recall from a previous session:
- This project formats with `ruff format` and lints with `ruff check`.
- We chose SQLite + FTS5 over Postgres for the local dev store.
Running `ruff check` before I start...
you> We just decided to switch auth to short-lived JWTs with refresh tokens in Redis.
codex> [calls perseus_remember {"category": "decision", "key": "auth",
"text": "Auth uses short-lived JWTs; refresh tokens live in Redis."}]
Remembered. I'll apply that convention going forward — including in
future sessions.
Tomorrow, in a brand-new session, perseus_recall "auth" returns that
decision. The context survived.
Try the demo
PERSEUS_VAULT_BIN=/path/to/perseus-vault python scripts/demo.py
It simulates two separate Codex sessions: session 1 learns three project facts
and tears the vault process down completely; session 2 — a fresh process —
recalls them, reflects on them, and reports encrypted status. Sample output is
in docs/.
Architecture
Codex (GPT-5.6) ──MCP stdio──▶ perseus-vault-codex ──MCP stdio──▶ perseus-vault binary
5 tools (this package) 55+ tools SQLite+FTS5, AES-256-GCM
Two hops on purpose: Perseus Vault exposes 55+ low-level memory tools; this
package collapses them into five verbs a coding agent can reason about, and the
binary does the encrypted storage and retrieval. Full write-up:
docs/architecture.md.
Benchmarks
Measured against the real perseus-vault binary (v2.17.0), encrypted at rest —
full methodology and reproducible harness in benchmarks/:
- Recall is fast and accurate at scale. Seeding 10,000 developer memories, recall runs at p50 7 ms (p95 27 ms) with 5/5 recall@10 on distinctive needle memories (1,000-memory corpus: p50 1.3 ms). The recall hot path — what a Codex agent hits every task — stays in single/low-double-digit milliseconds.
- The engine scales to 1,000,000 memories. A separate 2× H100 validation
(run
#619,results/scale_1m_2xh100.json) embedded ~1M memories (995,562 persisted, 0 errors) and hit hybrid recall@5 = recall@10 = 1.00 over 2,000 semantic queries, at sub-second latency (p50 479 ms). This is an engine-scale result on GPU, not the laptop path — reported separately and honestly (keyword-only recall is near-zero on that semantic workload; hybrid carries it). - Persistent memory cuts context tokens ~72%. Over a 30-session horizon, recalling the top-k relevant memories per task uses 110,493 fewer tokens (72.5% reduction) than re-priming each new session with the full project knowledge base — per-unit token costs measured with tiktoken against real vault recalls.
Every number is measured or explicitly labeled as a stated assumption; nothing is
hardcoded. Reproduce with python benchmarks/bench_recall.py and
python benchmarks/bench_token_savings.py.
How Codex was used
Codex was used during Build Week as an implementation and verification partner.
In the final review session, it read the complete wrapper and its tests, ran the
suite against the real perseus-vault 2.17.0 binary, exercised the two-session
demo, and checked a unique marker was absent from the raw default database file.
It also hardened stdout-EOF recovery in the subprocess client and added a
regression test. Those are review-session contributions; this README does not
attribute all pre-existing code to that session.
See SUBMISSION.md for the precise verification record and
benchmark caveats.
Development
git clone https://github.com/Perseus-Computing-LLC/perseus-vault-codex
cd perseus-vault-codex
pip install -e ".[dev]"
pytest -q # unit tests (no binary needed)
PERSEUS_VAULT_BIN=/path/to/perseus-vault pytest -q # + integration tests
About
Built by Perseus Computing LLC. Perseus Vault is the only fully-local, encrypted memory store for AI agents, with existing integrations for Haystack, LangChain, LlamaIndex, CrewAI, Pydantic AI, and Google ADK. MIT licensed.
Analysis
View
Metric
- 5
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- PythonIn code
- RustClaimed
1 of 2 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- Claude CodeCommits
- CodexConfig
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
117 KB
Source files
25
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
Perseus-Computing-LLC/perseus-vault-codex
34 files · 125 KB · @ b550934
Structure
Application logic
15 files · 44%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Python72%
- Markdown27%
- YAML1%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
pyproject.toml
pypi · 11 development-only dependencies.
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.