Nº 003 / GRIMOIRE

Grimoire is an Obsidian-based engineering knowledge system shared by Claude Code and Codex. Lightweight indexes guide agents to relevant decisions, constraints and verified lessons, carrying useful context across sessions without loading the entire vault.

Coding context is easily lost between sessions or tied to one agent's memory. Repeating decisions wastes attention; loading every note fills the context window with material unrelated to the task.

The challenge was to retain useful engineering knowledge while keeping retrieval selective, portable and efficient.

Plain Markdown notes form the shared store. A root INDEX.md leads to subindexes, each linking to focused notes. Agents follow relevant links and use targeted text search when the indexes are insufficient.

CLAUDE.md and AGENT.md both point Claude Code and Codex to the same vault, which instructs them how to retrieve, verify and maintain knowledge. Claude's native project MEMORY.md stays separate from the shared, long-term store.

Maintenance is instruction-driven: an active agent searches before writing, consolidates durable findings, updates the nearest index and marks superseded guidance. A read-only check_vault.py validates changed links and index coverage; current code and tests take precedence over remembered claims.

Designed the index-led retrieval structure and shared agent instructions, separating durable knowledge from temporary working context.

Audited the integrations, repaired broken entry links and populated empty indexes. Added a shared post-task grooming playbook and structural checker, preserving existing notes and native memory.

• Markdown
• Obsidian
• Claude Code
• Codex
• ripgrep

Both agents have a common, inspectable source of engineering context, with efficient navigation and focused notes that can be retrieved independently.

Omnis decisions and verified debugging lessons are retained with rationale and source references. The system is designed to reduce repeated explanations; token savings and retrieval quality have not been benchmarked.

Grooming runs through agent instructions and manual review during active sessions. No background memory service, scheduled cleanup or automatic conflict resolution is claimed.