omnymem v1

omnymem is a local-first tiered memory orchestrator for long-horizon, multi-agent coding workflows.

Omnymem decides what memory should be trusted, retrieved, promoted, invalidated, and shown to agents.

The project is inspired by mneme, but it takes a stricter orchestrator approach: tiered storage, deterministic promotion rules, explicit invalidation, projection-first retrieval, and defaults designed to reduce memory pollution rather than accumulate unbounded conversational residue.

Problem

Long-running coding agents lose useful context across restarts, branch switches, handoffs, and fresh sessions. Raw conversation replay is expensive and noisy. Unstructured agent memory also tends to drift, duplicate, and remain valid long after the underlying code changed.

For omnymem, memory is not "anything previously said". Memory = correct state over time.

Design Principles

• Low token consumption over maximal recall. The default target is the smallest valid working set that improves action quality.
• Deterministic hot paths over heuristic mutation. Retrieval, validation, promotion, and maintenance gates stay rule-based and inspectable.
• Event-first provenance with projection-first retrieval. Events exist for replay and lineage; compact projections and snapshots stay on the runtime path.
• Local-first durability over service sprawl. SQLite tiers, repo fingerprints, and optional adapters keep the kernel usable without external infrastructure.
• Canonical truth, derived summaries. Pointer files, snapshot bundles, and truth-delta reports explain state without replacing the underlying records.
• The pipeline should stay explicit: Admission -> Validation -> Storage -> Projection -> Retrieval -> Promotion -> Reconciliation.
• Prefer richer selection, not richer payload. The system should use stronger retrieval and bundle logic first, then export the smallest valid surface rather than inflating context.
• Under token pressure, coordination-critical memory should survive before generic facts: contradiction or stale markers, current task or blockers, active decisions, execution state, handoff notes, then supporting background.

Approach

omnymem splits memory into three tiers with explicit rules:

• Session memory captures short-lived, low-confidence working context
• Project memory stores durable repo-scoped facts, tasks, lessons, and decisions
• Long-term memory stores cross-project, highly trusted knowledge

The methodology is deliberately anti-pollution:

• confidence gates determine which tier can hold a memory
• semantic normalization profiles plus Jaccard similarity reduce duplicate noise without changing canonical stored content
• repo-state hashes force review when the codebase materially changes
• tier-aware invalidation propagation pushes downstream derived items into review_needed instead of leaving stale chains active
• supersession chains prevent old decisions from remaining active
• retrieval budget reservations keep bounded contradiction and pending-signal coverage when a bundle would otherwise collapse into one reinforcing cluster
• pointer generation and snapshot bundles only surface active, high-signal memory

This keeps retrieval useful without pretending that memory can be both permanent and noise-free by default.

Operationally, omnymem treats the memory pipeline as:

Admission -> Validation -> Storage -> Projection -> Retrieval -> Promotion -> Reconciliation

That keeps the write path, maintenance path, and retrieval path distinct instead of collapsing them into one opaque "memory layer".

Why omnymem

Dimension	Omnymem
Core identity	Memory validity/control layer
Main object	Events, projections, snapshots, memory items
Query model	Agent-facing retrieval bundles
Truth reliability	Core objective
Token efficiency	Core objective
Multi-agent policy	Core objective
Promotion/demotion	Core objective
Drift handling	Core objective
Best role	Orchestration memory control plane

Technically robust by design. Three independent SQLite stores give each tier its own WAL-mode database with optimistic locking on every write. There is no shared mutable state between tiers, so retrieval is zero-latency local I/O and a crash in one tier cannot corrupt another.

Repo-state hashing as a first-class signal. omnymem ties every memory to the literal state of the repository at write time using a SHA-256 over HEAD, working-tree status, diff output, and a file fingerprint sample. When the codebase materially changes, memories written against a different repo state are automatically flagged review_needed rather than silently serving stale context.

A retrieval compiler, not a retrieval lottery. retrieve-plan and pointer-bundle expose a deterministic compilation step: tier order, allowed memory types, item limits, and token budget are resolved once from the harness spec and query, then applied consistently. Machine clients receive a ranked, budget-bounded bundle with a token estimate and generated pointer text. Conditional diversity reservations keep contradiction markers and pending durable signals visible when a bundle would otherwise overfit to one fact cluster.

Role-scoped views over the same memory store. An architect, an implementer, and a reviewer working on the same project each receive a filtered view of coordination records and memory items appropriate to their role. The filtering is enforced in the coordination engine, not left to the caller.

Anti-pollution by default. Retrieval returns only active memories unless include_stale is explicitly set. Type-specific deterministic normalization catches noisy execution duplicates before they accumulate. Snapshot diff and lineage views expose changed truth without forcing raw history into the context window.

A coordination ledger, not just a memory store. The project tier includes a typed blackboard for multi-agent coordination: handoff notes, blockers, review findings, task claims, task-claim conflict records, and promotion gates.

Architecture Direction

omnymem is evolving as:

• a deterministic memory kernel
• bounded task-specific policy harnesses
• background reconciliation outside the hot path
• thin relation support for invalidation and handoff relevance
• event-backed provenance with canonical hot-path state
• offline benchmark-driven optimisation rather than runtime self-mutation

That keeps the project focused on long-horizon multi-agent memory orchestration instead of drifting into a general agent framework.

The current surface provides:

• a single binary
• SQLite-backed session, project, and long-term tiers
• transactional writes with optimistic locking
• deterministic retrieval harnesses for debug, refactor, review, handoff, incident, and architecture
• retrieval-plan inspection and compact pointer bundles for machine-facing clients
• semantic normalization profiles for noisy execution-like content
• tier-aware invalidation propagation over thin relations
• background reconciliation proposals for duplicate collapse, contradiction review, and session compaction
• explicit reconciliation approval and apply gates for high-consequence maintenance
• typed project coordination records for handoffs, blockers, review findings, task claims, and promotion gates
• promotion proposals, approvals, rejections, and apply flows
• consensus records
• review queue and audit trail inspection
• deterministic validation and invalidation
• bounded event replay with projection-window diagnostics and snapshot checkpoints for long-lived projects
• snapshot diff, lineage, and truth-delta inspection surfaces
• generated .omnymem/POINTERS.md
• optional contextCLI session-context enrichment
• optional local HTTP API
• optional portability surfaces for namespaces, projection export, identity, sync, and auto-wiring

Storage Layout

• Session: .omnymem/session.db
• Project: .omnymem/project.db
• Long-term: ~/.omnymem/longterm.db
• Pointer index: .omnymem/POINTERS.md

Tier Semantics

• Session is for confidence below 0.80 unless explicitly overridden
• Project is for confidence >= 0.80
• Long-term is for confidence >= 0.95 plus citations or consensus support

Validation can mark memories as:

• active
• review_needed
• stale
• superseded
• invalid

Commands

• omnymem init
• omnymem orchestrate
• omnymem memory update
• omnymem memory retrieve
• omnymem memory retrieve-plan
• omnymem memory pointer-bundle
• omnymem memory propose-promotion
• omnymem memory approve-promotion
• omnymem memory reject-promotion
• omnymem memory apply-promotion
• omnymem memory add-consensus
• omnymem memory summarize
• omnymem memory validate
• omnymem memory validation-history
• omnymem memory validation-report
• omnymem memory validation-health
• omnymem memory portability-status
• omnymem memory portability-export
• omnymem memory portability-render
• omnymem memory validation-timeline
• omnymem memory recovery-report
• omnymem memory golden-signals
• omnymem memory golden-signals-export
• omnymem memory reconcile
• omnymem memory reconciliation-proposals
• omnymem memory approve-reconciliation
• omnymem memory reject-reconciliation
• omnymem memory apply-reconciliation
• omnymem memory coordination-post
• omnymem memory coordination-list
• omnymem memory coordination-timeline
• omnymem memory workflow-history
• omnymem memory project-view
• omnymem memory relation-add
• omnymem memory relation-list
• omnymem memory relation-impact
• omnymem memory handoff-hints
• omnymem memory project-snapshots
• omnymem memory project-snapshot-capture
• omnymem memory project-snapshot
• omnymem memory project-snapshot-bundle
• omnymem memory project-snapshot-diff
• omnymem memory project-snapshot-lineage
• omnymem memory project-merge
• omnymem memory status
• omnymem memory events
• omnymem memory promotion-history
• omnymem memory review
• omnymem memory review-schedule
• omnymem memory audits
• omnymem memory supersession-chain
• omnymem memory longterm-report
• omnymem memory longterm-review
• omnymem memory longterm-quality
• omnymem memory graph
• omnymem memory graph lineage
• omnymem memory graph contradictions
• omnymem memory graph provenance
• omnymem benchmark import-scenario
• omnymem benchmark export-run
• omnymem benchmark export-bundle
• omnymem benchmark export-diagnostics
• omnymem benchmark optimize-report
• omnymem benchmark compare-variants

Build

go mod tidy
go test ./...
go build ./cmd/omnymem

Example

omnymem init
omnymem memory update --content "Parser panic reproduced in lexer.go" --type execution --confidence 0.62 --agent agent-1 --role implementer
omnymem memory retrieve --tier session
omnymem memory retrieve --harness debug
omnymem memory propose-promotion --source-tier session
omnymem memory approve-promotion --id "promo-id" --agent reviewer-1 --role reviewer
omnymem memory apply-promotion --id "promo-id" --agent architect-1 --role architect
omnymem memory validate
omnymem memory reconcile
omnymem memory reconciliation-proposals --status pending
omnymem memory approve-reconciliation --id "reconcile-id" --agent reviewer-1 --role reviewer
omnymem memory apply-reconciliation --id "reconcile-id" --agent architect-1 --role architect

Promotion And Validation

Promotion is explicit:

• propose-promotion scans eligible memories in a source tier
• approve-promotion transitions a proposal from pending to approved
• apply-promotion creates a new memory in the target tier and marks the proposal as applied

Long-term and other high-consequence promotion flows are intentionally operator-gated:

• durable promotion still requires explicit approval before apply
• reviewer or architect roles can act as promotion operators
• optional LLM-assisted review can inform a decision, but approval remains an explicit step

Validation is deterministic and local-first:

• expired validity windows become stale
• superseded items become superseded
• repo-state mismatches become review_needed
• upstream invalidation can flag downstream derived memories for review

No external service is required for those steps.

Reconciliation And Manual Gates

Reconciliation is proposal-driven:

• exact duplicate active memories can generate duplicate-collapse proposals
• contradictory active facts or decisions can generate contradiction-review proposals
• older low-confidence session residue can generate session-compaction proposals

Those proposals stay out of the hot path and do not silently rewrite authoritative memory records.

High-consequence reconciliation actions are intentionally manual-gated:

• approve-reconciliation records operator approval
• reject-reconciliation records explicit rejection with reason
• apply-reconciliation executes the approved maintenance effect

Current reconciliation operator roles are system, architect, and reviewer.

Scale And Replay Windows

omnymem uses a bounded event replay window for replayed projections and recovery reports. Hot-path retrieval stays projection-first, and replayed event views stay operationally bounded instead of scanning unbounded history.

Current behavior:

• replay windows are configurable with OMNYMEM_PROJECTION_REPLAY_LIMIT
• diagnostics and projection reports surface replay-window metadata
• project snapshots act as checkpoint anchors for long-lived histories
• snapshot diff and lineage surfaces provide compact changed-truth inspection rather than raw event dumps

HTTP API

The local HTTP API is optional and disabled by default. Set OMNYMEM_HTTP_ENABLED=true and optionally OMNYMEM_HTTP_BIND=:8080, then run:

omnymem orchestrate

Current endpoints:

• GET /healthz
• GET /v1/status
• GET /v1/retrieve
• POST /v1/update
• POST /v1/validate
• GET /v1/review

Optional Portability

IDE portability and bounded multi-user support should be optional in practical deployments. Many repos only need the local kernel, retrieval, validation, and coordination layers. So omnymem keeps portability surfaces off by default and exposes their state explicitly instead of silently assuming namespaces, sync, or adapter rendering are always wanted.

Current portability gates:

• OMNYMEM_PORTABILITY_ENABLED=true
• OMNYMEM_PORTABILITY_NAMESPACES_ENABLED=true
• OMNYMEM_PORTABILITY_PROJECTION_EXPORT_ENABLED=true
• OMNYMEM_PORTABILITY_IDENTITY_ENABLED=true
• OMNYMEM_PORTABILITY_SYNC_ENABLED=true
• OMNYMEM_PORTABILITY_AUTO_WIRE_ENABLED=true

Operational inspection:

• omnymem memory portability-status
• omnymem diagnostics

Current derived portability surfaces:

• omnymem memory portability-export emits a compact machine-facing export built from snapshot bundle, pointer bundle, and bounded truth-delta
• omnymem memory portability-render --target agents_md|claude_md|memory_md renders thin adapter files from that export
• --write writes the rendered file into the repo as AGENTS.md, CLAUDE.md, or MEMORY.md
• --namespace scopes memory, coordination, relations, snapshot bundle, and portability export using existing metadata channels instead of a new storage layer

This keeps the product shape stable:

• the local SQLite kernel remains canonical truth
• portability outputs stay derived edge surfaces
• sync is optional and never required for local correctness

Benchmark Integration

omnymem can participate in memory-validity-index runs through:

• omnymem benchmark import-scenario --scenario PATH
• omnymem benchmark export-run --scenario PATH --out RUN.json
• omnymem benchmark export-bundle --scenario-root PATH --out RUNS.json

That lets omnymem load benchmark scenario memories into its three-tier store, emit benchmark-compatible run artifacts, and be scored externally by the benchmark harness without embedding benchmark logic into omnymem itself.

Current bundle export matches the updated benchmark bundle contract:

• schema_version = "mvi-run-bundle-v1"
• run_count
• suite_name
• system_name
• include_holdout
• runs

The public run-artifact shape remains compatible with the benchmark scorer:

• system_name
• scenario_id
• selected_memories
• final_injection_order
• token_estimate
• task_outcome

Public Demo Result

Against the memory-validity-index public 100-scenario demo pack on 2026-05-10, omnymem produced:

• average_mvi_composite: 0.7836
• validity_precision: 0.9900
• validity_recall: 0.9767
• ordering_quality: 0.9517
• noise_load: 0.0000
• staleness_penalty: 0.0000
• budget_efficiency: 0.9900
• task_outcome_delta: 0.9900

This replaces the earlier public-demo claim that was produced without a hidden-oracle style check. The current benchmark path uses the objective scorer output from report_100_current_filebacked.json.

The run remains high precision with effectively zero noise, but it also exposes the remaining work in retrieval ordering and recall under pressure rather than presenting the public pack as solved.

The run used the benchmark's balanced public demo pack of 100 scenarios across 24 families with a declared aggregate scenario budget of 20,263 tokens and an estimated gold-valid memory payload of 9,137 tokens.

Token Savings

The session tier can be enriched with repo-local distilled context from contextCLI when present. That allows retrieval to include high-signal context snapshots instead of replaying recent raw events. The binary does not require contextCLI, but if it is available the orchestrator can merge its compact pointers and summary into session recall.

The retrieval compiler makes recurring work modes inspectable and machine-usable:

• retrieve-plan shows the deterministic tier order, allowed types, and retrieval limits for a query or harness
• pointer-bundle emits a compact ranked bundle with token estimate and generated pointer text

That gives editor and agent-runtime clients a stable, bounded context-packing surface instead of requiring them to reconstruct retrieval policy themselves.

Multi-Agent Coordination

The project tier includes a typed coordination surface that is AFP-compatible (AFP = Agent Federation Protocol, as seen in OmnyID) in shape without making AFP mandatory for users.

Current coordination features:

• typed handoff notes
• blockers
• review findings
• task claims
• automatic task-claim conflict routing
• project views filtered by role
• promotion gates surfaced as coordination events

The gate model is narrow by design. omnymem is not trying to become a workflow engine; it only gates durable memory transitions and reconciliation actions where silent mutation would damage trust.

contextCLI Integration

contextCLI is optional by design. When a repository contains .contextCLI/, omnymem can read:

• working_state.json
• current_context.json
• pointers.md

and can optionally use contextCLI resume latest for a richer distilled session snapshot.

It is not the source of truth for omnymem persistence. Session memory remains SQLite-backed so the orchestrator can preserve transactional writes, promotion state, and validation behavior consistently across tiers.

Zero-Noise Approach

This MVP does not claim a literal zero-noise guarantee. Instead it implements:

• confidence gating by tier
• supersession chains
• active-only retrieval defaults
• deterministic semantic normalization plus Jaccard similarity
• pointer generation that excludes stale, superseded, and low-confidence items
• compact truth-delta and lineage surfaces instead of raw historical replay

Planned Extensions

• memory-flow visibility: per-step memory trace, retrieval explanation, truth delta, and machine-facing lifecycle views without execution-replay bloat
• bounded multi-user portability work: identity metadata, optional sync, and simple auto-wiring without changing the local-first kernel
• richer editor integrations on top of the existing stdio transport and portability renderers
• controlled extraction and optional LLM-assisted validation judge behind deterministic admission and review gates
• graph-discipline extensions: deterministic relation queries, graph-like golden signals, and optional thin-relation export without introducing graph dependency
• hosted deployment and commercialization layers that keep edge services thin and preserve a regional stateful kernel