claude-memory-mcp: Instructions file for Codex

Mooncite repository contract

These instructions apply to the whole repository. Preserve the invariants below unless the owner explicitly changes the product contract.

Product boundary

Mooncite is a Linux/procfs-only, local, citation-backed retrieval tool for prior conversation history. Packaged local embeddings require Linux x64 and are skipped on other architectures. It helps an agent find and verify bounded evidence; it does not decide what evidence means, whether it is current, or what the user should do.

• Source history is user-owned and read-only. Never rewrite, repair, normalize in place, move, delete, or claim ownership of it.
• The SQLite evidence index is owner-private, transactional, derived, disposable, and rebuildable from authorized sources.
• Recall is lexical-first. An unquoted query of at least two terms may add local embedding matches after no strong lexical hit, and only when local embeddings are available. Quoted phrases and shorter queries stay lexical. Inspection must re-read and verify the current physical source bytes before returning a bounded window. Status must not expose transcript text or full physical paths.
• Mooncite has no history network transport, telemetry, upload, SSH/remote-copy path, account login, export automation, credential/cookie access, or opaque application-cache scraping. Text returned through MCP enters the receiving model's privacy boundary; do not imply otherwise.
• Evidence retrieval is not an authority, policy, recommendation, truth-scoring, or durable-agent-memory layer.

Fixed architecture

Treat these counts and seams as closed contracts:

• Exactly five source origins: Pi, OMP, Claude Code, Codex, and ChatGPT.
• Exactly three MCP tools: mooncite_recall, mooncite_inspect, and mooncite_status.
• Exactly four client integrations: Pi, OMP, Codex, and Claude Code. They connect to one local stdio MCP server. ChatGPT is a source origin, not a client integration.
• MoonciteEngine owns ingestion, source adapters, coherent reads, citation identity, SQLite/FTS, refresh/rebuild, inspection, last-good behavior, and the bounded canonical-anchor resolver.
• The Pi extension is a thin native-to-MCP adapter. .mcp.json, Codex, and Claude Code registrations point to the same packaged server. Do not duplicate retrieval behavior in an integration.
• Pi and OMP use their standard roots. Only the narrow supported Claude Code, Codex, and local ChatGPT-export roots may be automatically discovered. Owner configuration adds optional roots. A configured origin/root pair suppresses only the automatic registration with that exact pair. Automatic sibling roots remain active. Authorization grants local reads only.
• Symlinks are excluded from source admission. Authorized roots and opened files remain physically contained and identity-checked through Linux file descriptors.
• Incremental publication is transactional. Pi same-inode size growth may be admitted as append_trusted after a coherent suffix read. OMP same-inode size growth may use the same bounded path after physically verifying the last indexed evidence record; a failed boundary check replaces that source projection. These paths do not reread the already indexed prefix. Detectable Pi shrinkage, same-size rewrites, or identity changes retain the last-good generation. Other detected OMP changes and every detected change from supported mutable Claude Code, Codex, and ChatGPT producers replace that source projection transactionally. Never publish knowingly partial coverage over a usable generation.