memory-bridge

Cross-harness project memory for AI coding agents.

Memory Bridge transforms project context into versioned, human-readable files stored in the repo. Switch between OpenCode, Antigravity, Claude Code, Codex — .memory/ stays. It travels with Git. It's auditable. It belongs to the project, not to any single agent harness.

                    ┌─────────────────────────┐
                    │   NEUTRAL MEMORY        │
                    │   .memory/              │
                    │   (Markdown + JSON)     │
                    └───────────┬─────────────┘
                                │
        ┌───────────┬───────────┼───────────┬───────────┐
        │           │           │           │           │
   ┌────▼───┐  ┌────▼────┐  ┌──▼────┐  ┌───▼────┐
   │OpenCode│  │Antigrav.│  │Claude │  │ Codex  │
   │plugin  │  │.gemini/ │  │CLAUDE │  │AGENTS  │
   └────────┘  └─────────┘  │.md    │  │.md     │
    read/write   read via    └───────┘  └────────┘
                 sync         read via   read via
                              sync       sync

All four harnesses now supported. Bidirectional: what one agent learns can flow back to .memory/ and into every other agent.

The problem

Every agent harness stores memory in its own format — OpenCode plugins use local vector DBs, Claude Code uses CLAUDE.md, Antigravity uses .gemini/, Codex uses AGENTS.md. They don't talk to each other.

Build 3 hours of context in OpenCode, then open the same project in Antigravity: zero memory carried over. You start from scratch. Context dies trapped in the harness that created it.

The solution

A neutral memory layer outside any harness, versioned in the repo. Any agent working on the project reads the same base. A decision made in OpenCode is available when you open any other agent. Context survives tool switches.

This is the Git for agent memory — a shared format that every tool understands.

Store layout

.memory/
├── entries/              # explicit memories, markdown with frontmatter
│   └── 20260730-0001-*.md
├── decisions/            # optional ADR mirror
├── conventions.md        # human-maintained conventions
├── context.md            # context not in the source code itself
├── preferences.md        # user/team preferences
└── index.json            # searchable metadata index

index.json tracks every entry with id, type, tags, summary, createdAt, updatedAt, source, and path. Markdown remains the canonical readable format. No cloud, no embeddings, no vector DB, no automatic capture — memory is explicit and under version control.

Installation

git clone <repo>
cd memory-bridge
npm install
npm run build
npm link                  # makes `memory-bridge` available globally

OpenCode plugin

Add to your OpenCode config:

{ "plugin": ["file:///absolute/path/to/memory-bridge/dist/index.js"] }

The plugin exposes tools remember(text, tags?) and memory_search(query), and injects project memory into the first message of every session.

Usage

CLI

# Add a memory
memory-bridge add "This service has no NAT and uses public IP" --tag infra --tag network

# Add with flags before text (now works)
memory-bridge add --tag terraform --tag aws "Always pin provider versions"

# Search by text or tag
memory-bridge search NAT
memory-bridge search terraform aws

# List all memories
memory-bridge list

# Show full status (memory dump)
memory-bridge status

Sync (project memory → harness)

# Project to Antigravity
memory-bridge sync --to antigravity     # writes .gemini/memory-bridge.md

# Project to OpenCode
memory-bridge sync --to opencode        # writes .opencode/memory-bridge.md

# Project to Claude Code
memory-bridge sync --to claude          # injects section into CLAUDE.md

# Project to Codex
memory-bridge sync --to codex           # injects section into AGENTS.md

Generated files are read-only projections. Never edit them — edit .memory/ and re-sync.

Reverse sync (harness → .memory/)

Bring memory created outside OpenCode back into the neutral store:

# Dry-run first (default)
memory-bridge sync --from antigravity

# Apply changes
memory-bridge sync --from antigravity --apply

# Works with any harness
memory-bridge sync --from claude --apply
memory-bridge sync --from codex --apply

Reverse sync respects these rules:

• Exact duplicates are silently skipped (already in .memory/)
• Conflicts (similar but not identical text) are reported but never written — human must resolve
• New entries are added with source set to the harness name
• Dry-run by default — --apply to actually write

OpenCode tools (when plugin is loaded)

| Tool | Description | |------|-------------| | remember(text, tags?) | Records explicit memory with source: opencode. Rejects exact duplicates. | | memory_search(query) | Searches .memory/ index by text/tag. Case-insensitive. |

The plugin automatically injects project memory into session context on the first user message — the agent sees your conventions, context, and past decisions from the start.

Integration guides

Antigravity: sync --to antigravity → .gemini/memory-bridge.md. Point Antigravity project instructions at this file.

Claude Code: sync --to claude → injects a ## Project Memory Bridge section into CLAUDE.md. Re-runs replace the section in-place. Claude Code reads CLAUDE.md automatically.

Codex: sync --to codex → injects the same section into AGENTS.md. Codex reads AGENTS.md automatically as project guidance.

Conflict rules

• The canonical store (.memory/) is never overwritten by generated projections or reverse syncs.
• memory-bridge add rejects exact duplicate text with an explicit error.
• Lock-based concurrency protection prevents race conditions in addMemory.
• Reverse sync uses word-set Jaccard similarity for conflict detection (threshold: 0.5).
• Conflicts are reported on stdout and never written — the user edits .memory/ to resolve.

Validation

npm test                    # 14 tests: storage, dedup, all adapters, reverse sync
npm run typecheck           # strict TypeScript, zero errors
npm pack --dry-run          # verify package contents

Design principles

1. Neutral format — Markdown + JSON, readable by humans and any harness
2. Versioned — lives in the repo, travels with Git, auditable via diff
3. Explicit — nothing is captured automatically; you control what the agent "remembers"
4. Local-first — no cloud dependency, no third-party service, no lock-in
5. Portable — change harness, keep context. Same principle as ADRs

Roadmap

• [x] Core store (entries, index, CRUD)
• [x] OpenCode plugin (tools + auto-inject)
• [x] Antigravity adapter
• [x] Claude Code adapter (CLAUDE.md)
• [x] Codex adapter (AGENTS.md)
• [x] Lock-based concurrency protection
• [x] Reverse sync (bidirectional, conflict-safe)
• [ ] Optional semantic search (embedding)