Metadata-Version: 2.4
Name: codexmem
Version: 0.2.1
Summary: Local SQLite memory MCP server for Codex
Author: ghostarc249
License-Expression: MIT
Project-URL: Homepage, https://github.com/ghostarc249/codex-memory
Project-URL: Repository, https://github.com/ghostarc249/codex-memory
Project-URL: Issues, https://github.com/ghostarc249/codex-memory/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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`](https://github.com/dezgit2025/auto-memory), created by
[`dezgit2025`](https://github.com/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`:

```bash
pipx install codexmem
```

Then enable it for a repository:

```bash
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:

```bash
pipx install --editable .
```

## Quick Start

Add a memory:

```bash
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:

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

Check what the automatic recall hook would inject:

```bash
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:

```json
{"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:

```toml
[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.

```toml
[codex_memory]
min_semantic_context_score = 0.12
```

For one-off testing, use an environment variable:

```bash
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:

```bash
export CODEX_MEMORY_SCOPE=my-project
```

### Database Location

The default database path is:

```text
~/.codex/codex-memory/memory.db
```

Override it with:

```bash
export CODEX_MEMORY_DB=/some/path/memory.db
```

## Install Options

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```md
## 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

```bash
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`
