omp-episodic-memory v1.1.0
GitHub NPM
100% Offline Local Experience Memory

Forensic Experience Memory
For Coding Agents

Index raw Oh My Pi session transcripts to recall provenance-backed decisions, runbooks, and gotchas - without modifying agent state.

$ npm install -g omp-episodic-memory
Get Started Configure MCP

Data Pipeline Architecture

How raw transcripts turn into highly actionable agent context

01 / PARSE

Crawl JSONL

Walks sessions directory on disk and extracts exchange blocks.

Local Disk
02 / EMBED

Transformers.js

Generates local vectors via MiniLM-L6-v2 model. Zero API keys.

ONNX Runtime
03 / INDEX

SQLite SQLite-Vec

Stores hybrid index: FTS5 for text and vec0 for vector embeddings.

Hybrid Store
04 / FUSE

RRF Search

Combines FTS5 and vector matches into a unified ranked output.

RRF Formula

Why not just use built-in OMP memory?

Oh My Pi's built-in memory is curated and compressed - a distilled view optimized for the agent's working context. That is extremely useful, but it is lossy: the original wording, the dead ends, and the precise moment a decision was made are discarded.

The Curation Gap

When agents compress logs into facts, they throw away the "why" and the verbatim command syntax. When you hit a bug that was solved weeks ago, you need to see the exact logs, code block changes, and CLI outputs - not just a summaries saying "fixed X issue."

Forensic Provenance

Every retrieved result from omp-episodic-memory links directly back to the source session JSONL, user prompt, and assistant code block that solved it. You can track decisions through time, compare options, and review changes on the fly.

Quick Start

From install to your first provenance-backed recall in three commands.

1

Index sessions

Crawl your local Oh My Pi transcripts and build the hybrid SQLite index. Runs fully offline.

$ omp-episodic index
2

Search hybrid

Query across keyword and vector space, fused with RRF. Every hit cites its source session.

$ omp-episodic search "sqlite-vec build"
3

Recall for task

Assemble a confidence-tiered evidence bundle for the task at hand - or abstain when unsure.

$ omp-episodic recall "fix arm64 build"

Core Features

Modern, production-grade capabilities for professional coding environments

Hybrid Retrieval

Fuses Sqlite FTS5 keyword matching and vector matching into a unified ranking system via Reciprocal Rank Fusion (RRF).

Reviewable Memory Inbox

Automatically extracts candidate decisions, gotchas, and runbooks into a staging inbox. You decide what enters the permanent DB.

Evidence Bundles

Retrieved items include confidence metrics and source verification. Correctly abstains instead of fabricating answers.

Temporal Project Graph

Maps relationships over time with automatic supersession rules and diff outputs to check updates since a specific date.

Pinned Context Blocks

Pin durable markdown instructions, rules, or system details to projects to ensure they are always present in the context.

Eval Harness Gates

Comprehensive gold-set tests verifying retrieval precision, abstention recall, and model latency thresholds on CI.

Interactive Memory Inbox

Try approving and rejecting derived candidate memories dynamically below

Pending Inbox Staging

3 items pending
DECISION session-a8f2

Chose sqlite-vec over pgvector because the project requires a zero-dependency local SQLite file.

GOTCHA session-9b1c

Transformers.js model downloads are cached, but the first run will block vector searches. Pass mode: 'text' to bypass.

RUNBOOK session-c4d2

To regenerate the Gold Set index, run omp-episodic label-scaffold, review candidates, then run the bench command.

Approved Knowledge Base

0 items approved

No approved memories yet

Approve a candidate on the left and it lands here - committed to the permanent index with full provenance.

CLI Command Center

Execute forensically precise search commands directly in the terminal

omp-episodic-memory --help
bash
# Start indexing session logs $ omp-episodic index Scanning /Users/wolfie/.omp/agent/sessions... Found 42 session log files. [██████████████████████████████] 100% | 42/42 files Extracted 524 user-assistant exchanges. Generating local vector embeddings... [██████████████████████████████] 100% | 524 exchanges embedded Upserting SQLite indexes... Done! Index size: 2.4 MB.

MCP Server Configuration

Register the server in your favorite agent harness to expose episodic memory tools

Claude Code Config (claude_desktop_config.json) 
{
  "mcpServers": {
    "omp-episodic-memory": {
      "command": "npx",
      "args": ["-y", "-p", "omp-episodic-memory", "omp-episodic-mcp"]
    }
  }
}

Exposed Tools

search Hybrid retrieval over indexed sessions (markdown/JSON).
read Read a full session transcript securely by path.
recall_for_task Evidence bundle query with strict confidence tiers.
list_gotchas Fetch approved pitfall and failure-mode memories for a project.
get_project_context Pinned context blocks plus recent approved decisions/gotchas.

Gold Set Benchmarks

OMP-MemBench metrics verified on every pull request push. Baseline results on synthetic fixtures:

RECALL@5
100%
Gate floor: ≥ 85% in CI
ABSTENTION ACCURACY
100%
Gate floor: False Positive < 10%
EXTRACTION PRECISION
83.3%
Gate floor: ≥ 80% (target 85%)
p95 LATENCY
sub-ms
Gate floor: < 500ms on index query
Note on metrics: These results are measured on the bundled synthetic fixtures as a regression guardrail. Real-world query latencies depend on corpus size and embedding runtime, but text-mode lookups are designed to run in milliseconds by leveraging SQLite's native FTS5 indices.

Local Development

Episodic Memory utilizes Bun for rapid testing, typechecking, and package compiling.

# Install dev dependencies
$ bun install
# Type-check TypeScript codebase
$ bun run check
# Execute Node's native test runner via tsx
$ bun run test