# Codex Memory

Local Markdown-backed memory tools for Codex and other MCP-capable agents.

Codex Memory keeps durable agent knowledge in ordinary Markdown files, builds
local indexes for retrieval, and exposes the result through both a CLI and an
MCP server. It is designed for local-first use: your memory vault and session
transcripts stay on your machine unless you share them yourself.

## Features

- Markdown memory vault with simple YAML front matter.
- CLI commands for `doctor`, `write`, `read`, `search`, `reindex`, `hygiene`,
  and `weekly-hygiene`.
- MCP tools: `search_memory`, `read_memory`, `write_memory`,
  `reindex_memory`, and `memory_hygiene`.
- Local keyword retrieval with SQLite and an optional Tantivy helper.
- Optional semantic retrieval when `CODEX_MEMORY_ENABLE_SEMANTIC=1`.
- Local browser tools for recent sessions, agent monitoring, and report-board
  drafting.
- Codex hook entrypoints for session-start context and stop-time candidate
  capture.

## Install

Use Python 3.12 or newer.

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```

Build the optional Tantivy keyword helper:

```bash
cd rust/codex-memory-keyword
cargo build --release
```

The Python implementation still works without the helper, but keyword search is
faster after it is built.

## Quick Start

Copy the synthetic example vault to a writable location:

```bash
cp -R examples/memories /tmp/codex-memory-demo
```

Run the basic workflow:

```bash
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo doctor
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo reindex --force
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo search "demo workflow" --status active,risk_pending
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo hygiene
```

Create a new candidate memory:

```bash
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo write \
  --title "Demo candidate" \
  --body "A short note for later review." \
  --keyword Codex
```

## Configuration

Defaults are intentionally home-relative and overrideable:

- `CODEX_MEMORY_ROOT`: memory vault root. Defaults to `~/.codex/memories`.
- `CODEX_MEMORY_SERVICE_ROOT`: source checkout root used to find the optional
  Rust keyword helper. Defaults to the repository root in editable installs.
- `CODEX_MEMORY_ENABLE_SEMANTIC=1`: enables semantic indexing/search.
- `CODEX_MEMORY_TRANSCRIPT_ROOTS`: extra transcript roots for session and hook
  tests, separated by the platform path separator.
- `CODEX_MEMORY_PROJECT_SPECIFIC_TERMS`: comma-separated local lint terms used
  to flag records that should be filed under a concrete project instead of a
  shared knowledge-base project.

Every CLI command also accepts `--memory-root`.

## MCP Server

Start the MCP server with:

```bash
codex-memory-mcp
```

Example MCP client command configuration:

```json
{
  "command": "codex-memory-mcp",
  "env": {
    "CODEX_MEMORY_ROOT": "/absolute/path/to/your/memories"
  }
}
```

Available MCP tools:

- `search_memory(query, project?, type?, status?, limit=5, mode?, diagnostics=false)`
- `read_memory(id_or_path)`
- `write_memory(record, update_id?)`
- `reindex_memory(force=false)`
- `memory_hygiene(stale_days=30)`

`status` accepts comma-separated values such as `active,risk_pending`.
`read_memory` and `write_memory` reject absolute paths or `..` traversal outside
the configured vault.

## Local Browser Tools

All browser tools bind to `127.0.0.1` by default.

```bash
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo sessions ui --no-open
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo agents ui --no-open
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo reports ui --no-open
```

- `sessions ui` reads recent Codex JSONL transcripts from `~/.codex/sessions`
  and any extra `CODEX_MEMORY_TRANSCRIPT_ROOTS`.
- `agents ui` derives parent/subagent status summaries from local transcripts.
- `reports ui` searches the memory vault, lets you select/edit candidate
  material, and exports Markdown under `report-board-output/`.

These tools do not write transcripts, do not call external services, and do not
publish a network-facing endpoint unless you explicitly bind them elsewhere.

## Hooks

The package exposes two CLI hook commands:

```bash
codex-memory --memory-root /absolute/path/to/memories hook-session-start
codex-memory --memory-root /absolute/path/to/memories hook-stop
```

`hook-session-start` ensures the vault layout exists and returns compact startup
guidance. `hook-stop` reads an allowed local transcript and writes an inbox
candidate only when it sees reusable-experience signals such as blockers,
verified fixes, durable rules, or unresolved risks.

## Memory Format

Records are Markdown files with front matter:

```markdown
---
id: mem-demo-workflow
title: Demo workflow
project: demo-project
type: workflow
status: active
keywords:
  - Codex
  - demo
source: example
---
# Demo workflow

Use this record as searchable local context.
```

Supported `type` values are `candidate`, `project_profile`, `long_term_rule`,
`issue`, `build_flow`, `protocol`, `script`, `hardware_risk`, and `workflow`.
Supported `status` values are `candidate`, `active`, `risk_pending`, and
`archived`.

## Privacy

Do not publish your real memory vault or session transcripts. This repository
contains only code and synthetic examples. See `docs/privacy.md` for the full
local-data boundary.

## Development

Run the Python tests:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

Run the Rust helper tests:

```bash
cd rust/codex-memory-keyword
cargo test
```

Optional live-vault retrieval checks are skipped unless explicitly enabled:

```bash
CODEX_MEMORY_LIVE_GOLDEN=1 CODEX_MEMORY_LIVE_ROOT=/path/to/memories \
  PYTHONPATH=src python3 -m unittest \
  tests.test_markdown_store.MarkdownStoreTests.test_live_vault_golden_queries_when_enabled
```

## License

MIT.