# Install MindBridge in Codex and Claude Code

These instructions are for a local coding agent helping a user install
MindBridge as a **local STDIO MCP server**. Codex and Claude Code can share one
local memory store. Read the entire guide before changing anything.

## Product and safety boundary

- MindBridge stays local. Do not expose Postgres, Redis, Ollama or the MCP
  process to the public internet.
- Do not ingest transcripts, install the nightly scheduler, or write a test
  memory unless the user separately asks for that action.
- Do not overwrite an existing `.env` or existing `mindbridge` MCP
  registration. Inspect first and stop with a clear explanation on conflict.
- Never print secrets or include `.env` values in chat output.

## Requirements

- Claude Code supports macOS 13+, Windows 10 1809+ / Server 2019+, Ubuntu
  20.04+, Debian 10+ and Alpine 3.19+ on x64 or ARM64 with 4 GB+ RAM and an
  internet connection. See the
  [official installation page](https://code.claude.com/docs/en/installation).
- Claude Code requires Pro, Max, Team, Enterprise or Console access; the Free
  plan currently does not include Claude Code.
- MindBridge additionally needs Git, Python 3.11+, Docker and Ollama.
- Enough local disk for Postgres images and `bge-m3` (about 1.2 GB).

The production proof on this site was reproduced on a MacBook Pro with Apple
M1 Pro (8-core), 16 GB RAM, macOS 26.5.2 / arm64, Claude Code 2.1.226,
MindBridge Python 3.12.13, Docker 29.2.1 and Ollama 0.32.5. These are verified
values, not minimum requirements.

## Install

1. Reuse an existing MindBridge checkout when present. Otherwise ask where the
   user wants it, then clone:

   ```bash
   git clone https://github.com/cassieliang6709/mindbridge.git
   cd mindbridge
   ```

2. Prepare the local runtime without overwriting existing configuration:

   ```bash
   test -f .env || cp .env.example .env
   test -d .venv || python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   ollama pull bge-m3
   docker compose up -d db redis
   ```

   If Claude Code is not installed yet, use Anthropic's recommended native
   installer, then verify it:

   ```bash
   # macOS, Linux or WSL
   curl -fsSL https://claude.ai/install.sh | bash
   claude --version
   claude doctor
   ```

   On Windows PowerShell, use `irm https://claude.ai/install.ps1 | iex`.

3. Register the local MCP server:

   ```bash
   chmod +x scripts/run-mcp.sh scripts/install-codex-mcp.sh scripts/install-claude-mcp.sh
   command -v codex >/dev/null && scripts/install-codex-mcp.sh
   command -v claude >/dev/null && scripts/install-claude-mcp.sh
   command -v codex >/dev/null && codex mcp list
   command -v claude >/dev/null && claude mcp list
   ```

4. Do not claim a currently open client can see a newly installed MCP server.
   Restart Codex / Claude Code or open a fresh session. In that session,
   verify `/mcp` lists `mindbridge`.

## Put Claude Code and Codex history in one store

The MCP connection and transcript ingestion are separate paths that share the
same `MemoryService` and Postgres database:

```bash
# Reads ~/.claude/projects plus active and archived ~/.codex rollouts.
# The source directories are never modified.
.venv/bin/python -m ingest.runner --source all
.venv/bin/python -m ingest.runner --status
```

Claude Code rows are labelled `claude-code`; Codex rows are labelled
`codex-cli`. Byte cursors read only appended content, while `source_key` makes a
full replay idempotent. Tool arguments/results stay excluded by default.

## First safe test

Run two separate reads before asking to write anything:

> Call MindBridge's `get_daily_card` for the latest T2 card, then call
> `review_long_term_memory` for the newest three T3 records. Answer under
> separate T2 and T3 headings, cite every id, and do not write.

For an empty new store, explain that zero results is correct. If the user wants
to test a durable write, ask them for one non-sensitive preference and let the
MCP approval flow confirm `upsert_preference`. Then open another session and
query it again to demonstrate cross-session recall.

## Everyday use from Codex or Claude Code

MindBridge currently exposes eight tools:

- `get_daily_card` reads one T2 day card: what happened, observed facts and
  open threads. It does not change T3.
- `review_long_term_memory` lists T3 records newest-first for an explicit
  audit. Pass `namespace=operational` or `namespace=reflective` to inspect the
  lanes separately. It does not semantically rank results or bump access counts.
- `temporal_query` recalls relevant T3 memory, newest-weighted, and can search
  operational memory, reflective memory or both.
- `upsert_preference` stores durable operational memory by default. Reflective
  patterns, values and identity hypotheses are rejected unless the user has
  confirmed the wording and the call sets `confirmed_by_user=true`.
- `propose_pattern` creates a reviewable candidate only after at least three
  observations across two dates. It does not write T3.
- `review_pattern_candidates` shows supporting evidence, counter-evidence and
  current status.
- `resolve_pattern` records confirm/edit/reject. Confirm/edit writes reflective
  T3; reject keeps only the receipt.
- `get_daily_review` returns one Markdown-ready review containing T2, both T3
  lanes and pending candidates—useful for an Obsidian daily note.

Useful requests to give either coding agent:

### Review what happened today (T2)

> Call `get_daily_card` for the latest T2 card. Cite the card id and summarize
> completed work, observed facts and open threads. Do not infer a personality.

### Generate an Obsidian-ready daily review

> Call `get_daily_review` for the latest day. Keep the four sections separate:
> T2, operational T3, reflective T3 and pending Pattern Candidates. Return
> Markdown that I can save as today's Obsidian note.

### Review a possible recurring pattern

> List pending Pattern Candidates. Show all supporting evidence and
> counter-evidence before asking whether I confirm, edit or reject one. Do not
> call `resolve_pattern` until I answer explicitly.

### Audit what lasts across sessions (T3)

> Call `review_long_term_memory` for the newest ten T3 records. Separate current
> from superseded records and cite every memory id.

### Recall before doing work

> Query MindBridge for my writing preferences, cite the memory ids, then edit
> this essay.

### Store a durable preference

> Ask MindBridge to remember: explain technical ideas in plain language and
> start with a concrete example.

Do not store a password, API key, one-time instruction or short-lived task
detail as a preference.

### Supersede an old preference

> My preference changed: write the PRD in English first, then provide a
> separate Chinese version. Ask MindBridge to supersede conflicts.

### Audit history

> Check MindBridge for conflicts in my bilingual-document preferences. Include
> superseded records and cite every memory id.

## Choose a memory operating model

MindBridge does not replace or redirect Codex's native local Memories backend.
Codex-managed files under `~/.codex/memories/` are generated state: do not edit,
replace or symlink them as part of this installation.

### 1. Keep both stores — works today

Leave native Codex Memories enabled and use MindBridge over MCP alongside it.
This requires no migration and preserves native automatic memory injection, but
the two systems may retain overlapping or conflicting facts with different ids
and provenance.

### 2. MindBridge as source of truth — recommended target

Import reviewed native-memory records into MindBridge once, validate dedup and
provenance, then separately disable native memory generation and injection.
Codex, Claude and Cursor can then use the same MindBridge records through MCP.

This repository does not yet ship the native-memory importer. Do not claim the
migration is complete, and do not disable native Memories until the user has a
verified backup and an import report.

### 3. One-way import — safer transition

Periodically import generated Codex memory records into MindBridge without
writing changes back to Codex files. This preserves history and avoids sync
loops. It still leaves two physical stores until native Memories are disabled.

Required rules should remain in `AGENTS.md` or checked-in project documentation
under every model; memory recall is not a substitute for deterministic project
instructions.

## What is running

```text
Codex
  -> local STDIO MCP
MindBridge MemoryService
  -> Postgres / pgvector
  -> Redis exact-query cache
  -> Ollama bge-m3
```

The public MindBridge website uses synthetic data. Installing this local MCP is
what connects Codex to the user's own local memory store.