Verified, project-scoped memory for Codex.
Readable on disk. Recalled across tasks. Repairable when reality changes.

Install · Privacy · Troubleshooting · Contributing

---

Install

npx verimemo

VeriMemo supports Windows 10/11 and requires Node.js 20 or newer. It works with Codex Desktop, Codex CLI, and Codex tasks in ChatGPT Desktop.

One guided setup verifies Codex access and configures:

• a recommended multilingual semantic + exact FTS5 mode;
• a lightweight FTS5-only mode; or
• a custom local Sentence Transformers model.

VeriMemo then creates its isolated Python runtime, managed storage, hidden Windows hooks, background semantic service, and user-level verimemo command. Installation and updates are transactional.

For unattended installation with recommended settings:

npx verimemo --yes

Open a new Codex task after installation so the plugin hooks are loaded.

Stop rebuilding context from scratch

VeriMemo gives Codex a durable understanding of the project—not just a larger chat history. Decisions, constraints, fixes, verification results, and open work follow the project into the next task automatically.

Remember across tasks	Inspect everything	Correct the record
Start a new Codex task without repeating the architecture, recent work, or why a decision was made.	Durable memory is readable local Markdown with source, confidence, freshness, and lifecycle metadata.	Corrections supersede stale facts; lint, conflict detection, and reconciliation keep memory coherent.

No dashboard, hosted vector database, or manual storage setup is required. Recall and end-of-turn capture happen automatically.

How it works

1. A Codex hook captures the important handoff from the current task.
2. GPT-5.6 Luna extracts durable knowledge through the signed-in Codex client; writes are staged, validated, and committed atomically.
3. A new task receives pending context immediately, then relevant durable Markdown with provenance and freshness metadata.
4. Corrections replace stale facts instead of accumulating contradictions.

Reader and writer budgets are independent: recall places query-ranked answers before bounded pending/NOW auxiliaries, while Luna receives a smaller single-copy writer context. Safe exact duplicates can be rejected locally with zero writer tokens. Reader recall progressively selects a 480-token exact, 900-token clear, or 1,800-token causal/ambiguous budget under the 2,500-token safety ceiling. Paths, filenames, memory IDs, symbols, versions, error codes, and config keys have a dedicated exact lane; managed facts are indexed atomically, and a Decision expands to its causal parent only for why/risk/ consequence queries. Routine writes use the compact routine_delta protocol and automatically escalate to causal_maintenance when needed.

Supported clients

Client	Shared project memory	Support level
Codex Desktop	Yes	Automated + release smoke coverage
Codex CLI	Yes	Automated + release smoke coverage
ChatGPT Desktop · Codex tasks	Yes	Same plugin runtime + manual release check

All three clients resolve the same project identity and managed Markdown store on Windows.

Local, managed storage

Setup chooses the standard Windows data directory automatically:

%LOCALAPPDATA%\VeriMemo

Canonical Markdown lives under memory\Projects. Private indexes, queues, logs, tokens, and model state live separately under state and are never committed with project source.

The memory stays readable in any Markdown editor, including Obsidian.

verimemo storage path
verimemo storage open
verimemo storage move "D:\Private Data\VeriMemo Memory"

storage move pauses active writes, copies only managed Markdown, verifies each file by SHA-256, atomically switches configuration, and removes the old managed subtree only after a successful cut-over.

Everyday control

Command	Purpose
verimemo doctor	Diagnose installation, hooks, writer, service, and storage
verimemo status	Show queue, index, conflict, and freshness health
verimemo search "query"	Inspect what recall can find
verimemo lint --reconcile	Audit and repair Markdown, ledger, index, and lifecycle drift
verimemo remember "fact" --wait	Explicitly persist important project knowledge
verimemo storage open	Open the readable Markdown memory
verimemo update	Transactionally update the installation

Normal uninstall preserves Markdown memory:

verimemo uninstall

Deleting managed memory requires an explicit destructive flag:

verimemo uninstall --purge-data

Trust boundaries

• Markdown memory, SQLite indexes, queues, logs, and optional Hugging Face embeddings stay local.
• Bounded task excerpts are sent through the signed-in Codex client to GPT-5.6 Luna for memory extraction and use the user's Codex quota.
• The model chosen during setup is the local retrieval model; Luna remains the verified writer model.
• Redaction runs before persistence, post-model DLP runs before commit, service tokens are isolated, and recalled Markdown is treated as untrusted context.
• VeriMemo has no analytics or telemetry endpoint of its own.

Read the complete privacy and data-flow statement.

Engineering details

Reliability model

• Durable per-project queues with renewable leases and fencing tokens
• A bounded pending handoff for important uncommitted work
• Staged plans, conditional multi-file commits, rollback, and crash recovery
• Lifecycle-aware Decisions with provenance and freshness review
• Incremental conflict detection and deterministic reconciliation
• Stable-ID/Bayesian recall-usefulness feedback with correction resets
• Truncation-aware session continuation instead of permanently hidden tails
• Persistent HNSW retrieval for large vaults with exact small-vault fallback

Development

python -m pip install -r requirements-dev.txt
python -m ruff check plugins/verimemo
python -m pytest -q plugins/verimemo/tests
npm test
npm run test:e2e
npm run pack:audit

Repository layout:

• plugins/verimemo/ — plugin runtime, bundled skill, and Python tests
• installer/ and bin/ — dependency-free npm bootstrap and CLI
• .agents/plugins/marketplace.json — Codex marketplace manifest
• docs/ — privacy, troubleshooting, methodology, and visual assets

Release checks inspect npm pack --dry-run --json; tests, caches, memory, runtime databases, credentials, and local configuration stay outside the package.

License and security

VeriMemo is licensed under Apache-2.0. Report vulnerabilities using the private process in SECURITY.md; contribution rules live in CONTRIBUTING.md.

_{VeriMemo · local memory with a paper trail}