codexmem 0.2.1

Local SQLite memory MCP server for Codex

Codex Memory Kit

A minimal, local-first memory layer for Codex. It gives Codex a durable SQLite-backed project memory, an MCP server, and optional lifecycle hooks that can recall relevant context before a turn starts and save compact checkpoints after a turn ends.

The PyPI package is codexmem; the installed command is codex-memory.

Codex Memory Kit was inspired by auto-memory, created by dezgit2025. auto-memory brought automatic memory workflows to GitHub Copilot; this package adapts that idea for a Codex-native surface.

What it provides

• SQLite + FTS5 durable memory storage
• Local deterministic semantic search for wording drift
• MCP stdio tools for searching, adding, listing, and maintaining memories
• codex-memory CLI for install, health checks, search, and maintenance
• Optional Codex hooks for automatic recall, touched-file tracking, and checkpoint writeback
• Bounded recall so memory helps without flooding the model context

The default semantic provider is an offline hash vectorizer. Memory content is not sent to a remote embedding service.

Install

Install the package with pipx:

pipx install codexmem

Then enable it for a repository:

cd /path/to/your/repo
codex-memory install
codex-memory doctor
codex-memory health

codex-memory install updates ~/.codex/config.toml so Codex can use the MCP server, then writes repo-local hooks to .codex/hooks.json in the current repo.

For local development from this checkout:

pipx install --editable .

Quick Start

Add a memory:

codex-memory add \
  --scope my-project \
  --type decision \
  --title "Use Postgres as the default relational database" \
  --content "This project uses PostgreSQL as its default relational database. New persistence work should assume PostgreSQL unless explicitly stated otherwise." \
  --tags database postgres persistence

Search it:

codex-memory search "postgres persistence" --scope my-project --limit 5

Check what the automatic recall hook would inject:

printf '{"cwd":"%s","prompt":"postgres persistence"}' "$PWD" \
  | codex-memory hook user-prompt-submit

If there is a relevant match, the output includes hookSpecificOutput.additionalContext. If there is no relevant match, it returns:

{"continue": true}

That empty result is intentional: unrelated memories are not added to the model context.

How Automatic Recall Works

When project hooks are installed, Codex can run these commands during its normal lifecycle:

• UserPromptSubmit: searches local project memory before the model starts.
• PostToolUse: records files touched by Codex tools.
• Stop: saves a compact checkpoint from the final assistant response.

Recall is scoped to the current git root directory name by default. For normal prompts, the hook only injects memories that pass relevance checks:

• exact FTS matches are allowed
• semantic-only matches must meet min_semantic_context_score
• recent files are included only when there is relevant memory
• continuation prompts can include recent checkpoints and touched files

Injected context is bounded:

• up to 4 memories
• up to 5 recent files
• up to 700 characters per memory excerpt
• up to 5000 characters total

These limits are deliberately conservative so automatic memory does not unnecessarily consume the model context window.

Configuration

codex-memory install manages the required Codex settings for you. The resulting configuration in ~/.codex/config.toml looks like this:

[features]
memories = true
codex_hooks = true

[codex_memory]
min_semantic_context_score = 0.18

[mcp_servers.codex_memory]
command = "codex-memory"
args = ["mcp"]
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 30

Recall Threshold

min_semantic_context_score controls how strict semantic-only recall should be. The default is 0.18.

Lower values recall more aggressively and may add more context. Higher values save more tokens but may miss weaker wording matches.

[codex_memory]
min_semantic_context_score = 0.12

For one-off testing, use an environment variable:

export CODEX_MEMORY_MIN_SEMANTIC_CONTEXT_SCORE=0.12

Scope

The default scope is the current git root directory name. Override it when you want multiple checkouts to share a memory scope:

export CODEX_MEMORY_SCOPE=my-project

Database Location

The default database path is:

~/.codex/codex-memory/memory.db

Override it with:

export CODEX_MEMORY_DB=/some/path/memory.db

Install Options

codex-memory install --repo /path/to/repo
codex-memory install --no-global-config
codex-memory install --no-project-hooks

Project-local hooks only run when Codex trusts the project .codex/ layer.

CLI Reference

install

Configures Codex Memory for a repository. By default it updates ~/.codex/config.toml and writes .codex/hooks.json in the current git repo.

Useful options:

• --repo /path/to/repo: install hooks into a specific repository.
• --no-global-config: skip changes to ~/.codex/config.toml.
• --no-project-hooks: skip writing .codex/hooks.json.

doctor

Runs an end-to-end installation check. It verifies the merged Codex config, project hooks, database health, and a write/search roundtrip.

Useful options:

• --repo /path/to/repo: inspect a specific repository.
• --scope my-project: use a specific memory scope for the roundtrip.
• --no-roundtrip: skip the database write/search probe.

health

Shows a terminal-friendly health report for the local memory database, including schema status, corpus size, embedding coverage, and scope coverage.

Use --json when you want the raw machine-readable payload:

codex-memory health --json

schema-check

Checks that the SQLite database has the expected tables, columns, metadata, and embedding rows. It exits with a non-zero status if schema problems are found.

add

Stores a memory record.

Required fields:

• --scope: project or repository scope.
• --type: one of decision, constraint, pattern, task_context, pitfall, or note.
• --title: short label for the memory.
• --content: the durable context to remember.

Optional fields:

• --tags: zero or more tags used for filtering and display.
• --source: optional origin identifier, useful for generated checkpoints.

search

Searches memories. The default mode is hybrid, which combines FTS5 exact matching with local semantic matching.

Useful options:

• --scope my-project: restrict results to one scope.
• --limit 5: limit result count.
• --days 7: only search recently updated memories.
• --mode fts: exact/project-term search.
• --mode semantic: wording-drift search.
• --mode hybrid: combined search.

list

Lists recent memories, newest first.

Useful options:

• --scope my-project: restrict to one scope.
• --limit 20: limit result count.
• --days 30: only show recently updated memories.
• --type decision: filter by memory type.

show

Displays one memory by numeric id:

codex-memory show 12

files

Lists recently touched files tracked by the PostToolUse hook. This helps Codex resume work with awareness of files that were recently read or edited.

Useful options:

• --scope my-project
• --limit 10
• --days 7

checkpoints

Lists task_context memories written by the Stop hook. These are compact continuation notes from previous Codex turns.

Useful options:

• --scope my-project
• --limit 5
• --days 7

embeddings

Maintains local semantic-search vectors. Currently the supported action is:

codex-memory embeddings rebuild --scope my-project

Use this after changing embedding behavior or when schema-check reports missing embedding rows.

forget

Deletes a memory by numeric id:

codex-memory forget 12

Use this for stale, wrong, or overly noisy memories.

hook

Runs a Codex lifecycle hook command. You usually do not call this manually; codex-memory install wires it into .codex/hooks.json.

Supported hook events:

• user-prompt-submit: searches memory before a prompt reaches the model.
• post-tool-use: records touched files after Codex tool calls.
• stop: writes a compact checkpoint after a Codex turn.

Manual hook checks are useful when tuning recall:

printf '{"cwd":"%s","prompt":"postgres persistence"}' "$PWD" \
  | codex-memory hook user-prompt-submit

Project Policy

You can add a policy block to your repo AGENTS.md so future Codex sessions know how to use project memory:

## Codex Memory Policy

Before making a plan or editing code, search project memory for relevant decisions, constraints, patterns, and known pitfalls.

Use the `codex_memory` MCP server:
- `memory_search` before planning work.
- `memory_add` after durable architectural decisions, implementation patterns, or project constraints are discovered.
- `memory_list` to review recent memories.
- `memory_files` to review recently touched files.
- `memory_checkpoints` to review recent task-context writebacks.
- `memory_forget` to remove stale or wrong entries.

Never store:
- secrets, tokens, connection strings, private keys, credentials
- personal/sensitive data
- temporary debugging noise
- low-confidence assumptions

Prefer storing:
- architectural decisions
- codebase conventions
- migration status
- performance/security constraints
- reusable implementation patterns

CLI Examples

codex-memory add \
  --scope my-project \
  --type decision \
  --title "Use handlers for business logic" \
  --content "HTTP endpoints should stay thin. Move business behavior into handlers or services." \
  --tags architecture handlers

codex-memory search "business logic should not live in endpoints" --scope my-project
codex-memory search "handler architecture" --scope my-project --mode semantic
codex-memory list --scope my-project --limit 10
codex-memory files --scope my-project --limit 10 --days 7
codex-memory checkpoints --scope my-project --limit 5
codex-memory show 1
codex-memory schema-check
codex-memory embeddings rebuild --scope my-project

MCP Tools

• memory_search
• memory_add
• memory_list
• memory_show
• memory_files
• memory_checkpoints
• memory_forget
• memory_health
• memory_schema_check
• memory_embeddings_rebuild