Observational Memory

One local memory for your AI coding agents — so every session starts knowing your work instead of starting over.

Observational Memory, or om, watches what you do with Claude Code, Codex, OpenCode, Kimi Code CLI, Grok Build TUI, and Claude Cowork (Hermes joins through its plugin), distills it into plain Markdown on your machine, and hands every new session a compact memory summary. What Claude learns today, Codex knows tomorrow.

• No more cold starts. Every session begins knowing who you are, how you work, and what you were doing.
• One memory across agents. Switch tools without losing context.
• Your memory is yours. Plain Markdown files on your machine — readable, searchable, backed up, never silently uploaded.

New in v0.9.0

v0.8.0 made memory trustworthy. v0.9.0 makes that memory broader and safer to leave running:

• OpenCode support - om install --opencode installs a global OpenCode plugin plus an AGENTS.md fallback, so OpenCode sessions can receive bounded startup context and write message events back into OM-owned logs.
• Kimi Code CLI support - om install --kimi wires Kimi lifecycle hooks for startup context and prompt/subagent/failure checkpoints without scraping private provider data.
• Bounded background observation - installed hooks and scheduler backstops now use a single om observe-worker lane with concurrency control, timeouts, stale-lock recovery, atomic writes, and a Claude transcript backstop.
• Public roadmap additions - new plans cover optional OKF import/export, signed binary and desktop installers, and a future desktop coordination layer.

OM Mail remains an experimental preview from v0.8.0: agents can exchange signed notes, encrypted context packs, and recall requests over email, but handshake tokens, live listening, digests, and team trust roots are deferred to a future 0.x release. See how it works.

Aside browser support is also under active development in draft PR #98; it is not part of v0.9.0.

Everything is additive and defaults are unchanged. Full details: v0.9.0 release notes.

Upgrading from 0.6.x or 0.7.x?

brew upgrade observational-memory   # or: uv tool upgrade observational-memory
om doctor

No config changes needed. New integrations are opt-in unless you run om install --all; installed background observers become more conservative and skip when another worker is already running.

Quick Install

macOS with Homebrew:

brew install intertwine/tap/observational-memory
om install
om doctor

Linux, macOS, or Windows with uv:

uv tool install observational-memory
om install
om doctor

om install sets up Claude Code and Codex by default (--all adds OpenCode, Kimi, Grok, and Cowork) and asks which LLM provider to use — a metered API key, or your existing ChatGPT or SuperGrok subscription via om login. If you use Anthropic through Vertex AI or Bedrock, install with uv tool install "observational-memory[enterprise]" instead of Homebrew, then run om install.

How Memory Flows

flowchart LR
    A["Claude Code, Codex, OpenCode, Kimi, Grok, Cowork, Hermes logs"] --> B["om observe"]
    C["Claude auto-memory files"] --> D["search index"]
    C --> F
    B --> E["observations.md"]
    E --> F["om reflect"]
    F --> G["reflections.md"]
    G --> H["profile.md + active.md"]
    H --> I["om context startup pack"]
    E --> J
    G --> J["om recall / om search / om talk"]
    G -. opt-in .-> K["om cluster sync / om mail"]

First Week Workflow

1. Install om.
2. Run om install and answer the provider questions.
3. Run om doctor.
4. Use Claude Code, Codex, OpenCode, Kimi, or Grok normally — memory accumulates on its own.
5. Search memory when you need it:

om recall --query "current project status"
om search "release checklist"

6. Talk to your memory (experimental — it works, but flags may change), or check what new sessions will see:

om talk --query "what was I working on last week?"
om context --for codex --cwd "$PWD" --task "finish docs"

Where Your Memory Lives

om keeps four plain-Markdown files you can read, search, and back up:

Common Commands

om status
om doctor                       # health check, now with memory-growth report
om observe --source codex
om reflect
om reflect --check-conflicts    # reflect + flag silently-changed high-stakes facts
om reflect --async              # offline OpenAI Batch job at ~50% of the synchronous price
om jobs poll                    # apply completed async jobs
om backup --reason pre-experiment
om restore --list
om recall --query "what was decided about sync?"
om talk
om search "preferences" --json
om usage status                 # token usage, cost, and budgets
om usage budget set --daily-usd 5.00
om context --quality-report     # startup-context dedup / freshness / budget report
om export --target chatgpt

Multi-machine and agent-to-agent memory are opt-in:

# OM Cluster: encrypted full sync across YOUR machines
om cluster init --name "Personal Memory" --transport filesystem:~/Sync/om-cluster --import-existing
om cluster sync

# OM Mail (experimental): selective memory exchange between DISTINCT agents.
# Peers must exchange and pin keys first — see docs/mail-memory.md.
om mail init --username my-agent
om mail peers add peer@agentmail.to --key <PEER_PUBLIC_KEY> --shared-key <SHARED_KEY>
om mail send-note peer@agentmail.to --text "decision: ship v0.9.0"
om mail sync

Do not sync ~/.local/share/observational-memory/ directly with Dropbox, iCloud, Syncthing, rsync, or a NAS. Use the cluster transport directory instead.

Agent Support

Out-of-tree integrations have first-class seams: mail providers and CLI add-ons plug in through public entry points (CONTRIBUTING.md).

Architecture At A Glance

• om observe turns transcripts into recent notes.
• om reflect turns recent notes into durable memory — with provenance, scope rules, and a safety snapshot first.
• om context gives agents a bounded memory summary at session start.
• om recall, om search, and om talk retrieve more when that summary is not enough.
• om export prepares reviewed memory seed bundles for hosted systems.
• om cluster syncs encrypted records across machines when you opt in.
• om mail (experimental) exchanges signed memory between distinct agents over email.

Guides

• Documentation index
• Install and setup
• Platform integrations
• Hermes plugin
• Search, recall, and startup context
• Talk to your memories (om talk)
• Configuration
• OM Cluster sync
• OM Mail: email inboxes as a memory substrate (experimental)
• OM Cluster validation checklist
• Host memory coexistence
• Maintainer guide

Version

Current release: v0.9.0 — release notes. Built on v0.8.0's trustworthy-memory release, v0.7.0's section-targeted reflection, and the v0.6.x usage/budget and async-Batch subsystems. Maintainers: the release workflow lives in docs/MAINTAINERS.md.

Contributing

The om core is MIT licensed and stays that way. Pull requests are welcome — see CONTRIBUTING.md for development setup and contributor terms (DCO sign-off plus a relicensing grant to Intertwine AI, the project steward, which also builds separately licensed team add-ons on the core's public plugin interfaces).