🧠 OmpKeep

High-density blueprint for OmpKeep, the clean, best-practice OMP extension.

---

1. 🚀 Quick Start

Commands are registered in the OMP extension shell with a / prefix.

Command	Action	Key Options
/memory-doctor	Diagnostic health summary	None
/memory-diagnostics	Runs data integrity and secret scans	--save
/memory-graph	Exports memory relationship graph	--save
/memory-timeline	Displays record validity timelines	--memory <id>, --save
/curate-memory	Interactive patch review TUI panel	--mode=propose|auto
/maintain-memory	Overdue decay curation & recommendations	--mode=propose|auto, --report
/consolidate-memory	Trigger manual session LLM consolidation	None
/memory-handoff	Generate state snapshots for new subagents	--goal <text>

---

2. 🔧 Directory Layout

Persistent data is stored by priority:

1. OMP_MEMORY_ROOT environment variable
2. OMPKEEP_ROOT environment variable
3. PI_MEMORY_ROOT environment variable
4. Legacy directory ~/.pi/agent/pi-memory/ (if it exists)
5. Default directory ~/.omp/agent/omp-memory/

Local settings overrides cascades in settings.json:

• {cwd}/.omp/settings.json looking for "ompkeep".localPath or "omp".localPath (with subfolder /omp-memory)
• {cwd}/.pi/settings.json looking for "pi-persistent-intelligence".localPath or "pi-pi".localPath (with subfolder /pi-memory)

~/.omp/agent/omp-memory/  (or legacy ~/.pi/agent/pi-memory/)
├── memory/
│   ├── L1.identity.jsonl       # Core identity records (Human ratification only)
│   ├── L2.playbooks.jsonl      # Working workflow records (Auto-curated or manual)
│   ├── evidence.jsonl          # Trust/provenance records with bounded excerpts
│   ├── tombstones.jsonl        # Delete markers preventing record re-creation
│   ├── reinforcement.jsonl     # Outcome logs used for stability adjustments
│   └── inquiries.jsonl         # Open questions triggered by context matching
├── daily/                  # Daily logs matching YYYY-MM-DD.md
├── inbox/                  # Captured candidate records before curation
│   └── captured.jsonl      # Bounded candidate writes
├── patches/                # Pending patch files containing memory changes
├── search/                 # FTS5 search index
└── config.json             # Configuration

---

3. 📦 Hook Registration

OmpKeep hooks directly into the OMP lifecycle events.

export interface OmpExtensionAPI {
  on(
    event: "session_start" | "before_agent_start" | "agent_end" | "session_shutdown",
    handler: (event: any, ctx: any) => Promise<any> | any,
  ): void
  registerTool(def: {
    name: string
    label: string
    description: string
    parameters: unknown
    execute(id: string, params: any): any
  }): void
  registerCommand(
    name: string,
    def: { description: string; handler(args: string, ctx: any): void },
  ): void
}

Hook Pipeline Details

• session_start: Resolves the project profile context, synchronizes FTS5 indices, and parses/exports Markdown session summaries.
• before_agent_start: Evaluates pending inbox candidates, launches the inbox overlay TUI, and injects context blocks into the agent turn.
• agent_end: Scans user turns for corrections/Guidance patterns and populates local user/assistant turn buffers.
• session_shutdown: Runs LLM consolidation (Claude Haiku-powered candidate extraction) and triggers auto-curation patches.

---

4. 💡 Injection Pipeline

Context retrieval uses a tiered, budget-bounded assembly pipeline.

[User Prompt] ──> [FTS5 + Semantic Vector Search] ──> [Scope Filter] ──> [Negative Filter] ──> [Budget Assembly]

1. Relevance Selection: Retrieves top maxRecords candidates using hybrid SQLite FTS5 index and qmd vector search.
2. Profile Scope: Excludes records belonging to other repository profiles or hashes.
3. Basic Scope: Drops project-scoped records that do not match the current working directory.
4. Negative Scope: Removes records whose does_not_apply_when or known_exceptions match terms in the current prompt.
5. Context Compaction: Assembles the selected statements under category prefixes (⚠️ AVOID:, ✓ PREFER:, 📌 CONVENTION:) into a compact Markdown injection block.

---

5. 🚨 Gotchas & Safety

• 🚨 Precedence: Programmatic settings in config.json override runtime defaults; L1 records never auto-apply.
• 🚨 Secret Blocking: Candidates matching secret-like regex signatures are blocked immediately before serialization.
• 🚨 Memory Leak: Watchers and polling timers must be fully cleared in session_shutdown to avoid process leaks.
• 🚨 Nginx Rule: Any static Markdown representation (MEMORY.md) is a projection; JSONL files remain the sole source of truth.

---

6. 🔍 Curation Rules

Curation requires deterministic validation before mutating memory.

• Tombstone Check: Candidates attempting to recreate a tombstoned record ID must be rejected.
• Provenance Check: Candidate text must share at least 35% overlap coverage (matched statement tokens divided by total statement tokens) with its supporting evidence.
• Poisoning Gate: Auto-curation is blocked if a candidate is sourced from repository text or third-party documentation.
• Decay Cycle: Overdue playbooks lose confidence (0.05 for stable, 0.15 for semi-stable) on each maintenance loop.