Skip to main content
Glama
zhangtian-123

Codex Memory

by zhangtian-123
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

Related MCP server: Jarvis Markdown MCP

Install

Use Python 3.12 or newer.

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

Build the optional Tantivy keyword helper:

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:

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

Run the basic workflow:

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:

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:

codex-memory-mcp

Example MCP client command configuration:

{
  "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.

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:

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:

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

PYTHONPATH=src python3 -m unittest discover -s tests

Run the Rust helper tests:

cd rust/codex-memory-keyword
cargo test

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

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.

Available Tools

5 tools
memory_hygieneB

Report local memory hygiene issues such as stale candidates and duplicates.

ParametersJSON Schema
NameRequiredDescriptionDefault
stale_daysNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side effects, permissions, or whether the operation is read-only beyond the word 'report'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, but it could benefit from additional context without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with one parameter and an output schema, the description covers the basic purpose but omits details about the parameter's role and what the output contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter 'stale_days' lacks any description in the schema or in the tool description, which does not add meaning beyond the name and default value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports memory hygiene issues like stale candidates and duplicates, distinguishing it from siblings that read, reindex, search, or write memory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking hygiene issues but provides no explicit guidance on when to use versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_memoryA

Read a local memory record by id or path.

ParametersJSON Schema
NameRequiredDescriptionDefault
id_or_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It states it reads a record, implying read-only behavior. No additional behavioral traits (side effects, auth needs) are disclosed, but for a simple read operation this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, zero waste, front-loads action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and an output schema. Description is sufficient for a read operation; return values are covered by output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage; description partially compensates by stating 'by id or path', adding meaning that the parameter can be either an id or a path. However, it lacks format or examples, so it does not fully compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses verb 'Read' and specifies resource 'local memory record' with retrieval method 'by id or path'. This clearly distinguishes from sibling tools like 'search_memory' (searching) and 'write_memory' (writing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies when to use (retrieve a memory record) but does not explicitly state when not to use or mention alternatives. However, given sibling tool names, context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reindex_memoryC

Rebuild local memory indexes.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose whether rebuilding is destructive, safe to run concurrently, or requires any permissions. The agent gets no information about side effects or operational impacts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (4 words), which is efficient but at the cost of missing critical information. It is front-loaded with the verb, but every word is earned. A slightly longer description would improve value without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, return values are covered. However, the description lacks explanation of the 'force' parameter and does not provide enough context for a maintenance operation that could be impactful. The description is incomplete for safe and correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter, 'force', with a boolean type and default false, but the description does not mention it or explain its semantics. With 0% schema description coverage, the description fails to add any meaning beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Rebuild local memory indexes' clearly states the verb (rebuild) and the resource (local memory indexes). It distinguishes from siblings like read_memory or search_memory because rebuilding is a maintenance operation. However, it lacks detail on what indexes specifically are being rebuilt or why.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like memory_hygiene. It doesn't mention prerequisites, when not to use it, or how it fits into a workflow. An agent would have no context for selecting it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_memoryA

Search local Codex memory with keyword, semantic, or hybrid retrieval.

Use comma-separated status values such as "active,risk_pending" to search more than one lifecycle state. Set diagnostics=true to return hits plus per-stage timing fields for retrieval performance troubleshooting.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNohybrid
typeNo
limitNo
queryYes
statusNo
projectNo
diagnosticsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must convey behavioral traits. It mentions that diagnostics=true adds per-stage timing fields, but it does not state that the operation is read-only (non-destructive), nor does it explain the behavior of filters like type or project, or how results are ordered. The information is partially transparent but lacks full disclosure of expected behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences plus a usage tip. It front-loads the purpose and then provides parameter details. Every sentence adds value with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (7 parameters, no annotations, output schema exists), the description covers the main use case and key parameters. It explains query modes, status filters, and diagnostics. However, it does not explain the 'type' and 'project' parameters, nor does it state that the operation is read-only. The presence of an output schema reduces the need to describe return values, but some behavioral gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 7 parameters with 0% description coverage. The description adds meaning for several parameters: it explains that 'query' is required, 'mode' defaults to hybrid, 'limit' defaults to 5, 'status' can be comma-separated, and 'diagnostics' triggers timing fields. However, it omits explanations for 'type' and 'project' parameters, meaning some parameters remain underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search local Codex memory with keyword, semantic, or hybrid retrieval.' It specifies the verb (search), the resource (local Codex memory), and the retrieval modes, making it easily distinguishable from sibling tools like read_memory (single retrieval) or write_memory (writing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful tips for usage, such as using comma-separated status values and enabling diagnostics for troubleshooting. However, it does not explicitly state when to use this tool versus alternatives like read_memory or memory_hygiene, nor does it mention any prerequisites or exclusions. The guidance is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_memoryC

Create or update a Markdown memory record.

ParametersJSON Schema
NameRequiredDescriptionDefault
recordYes
update_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear full burden. It only states the action without disclosing behavioral traits like idempotency, side effects, or what happens on update (e.g., partial vs full replacement). This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) but sacrifices necessary detail. It captures the essence but leaves the agent without enough information to use the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (nested object, optional update_id, and output schema not shown), the description is too brief. It lacks guidance on how to construct the record input and how updates work, making it incomplete for reliable usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the parameters. It does not clarify what fields the 'record' object should contain, nor the purpose of 'update_id' (e.g., to specify which record to update).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Create or update' and the resource 'Markdown memory record', distinguishing it from siblings like read_memory, search_memory, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for writing memory records but provides no explicit guidance on when to use vs alternatives, or when to create vs update. The update_id parameter hints at update logic, but it's not explained.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedmemory_hygiene
    • First observedread_memory
    • First observedreindex_memory
    • First observedsearch_memory
    • First observedwrite_memory
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: hygiene, read, reindex, search, and write. No two tools overlap in functionality, ensuring an agent can easily differentiate them.

Naming Consistency4/5

Four tools follow a consistent verb_noun pattern (read_memory, reindex_memory, search_memory, write_memory), while memory_hygiene uses a noun_noun pattern, causing a minor deviation.

Tool Count5/5

With 5 tools, the server is well-scoped for memory operations. The count feels sufficient without being excessive or insufficient for the domain.

Completeness3/5

The server covers core read, write, search, and maintenance operations, but lacks a delete tool, which is a notable gap in lifecycle coverage.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • GPTkms

    sc28249782
    A
    license
    Not graded
    quality
    B
    maintenance
    Local-first Knowledge Management System that exposes markdown-based durable memory as MCP tools for Codex and ChatGPT, enabling search, read, write, and promotion workflows with project and global scopes.
    MIT

  • mnema

    Ray0907
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides a file-first personal memory layer for AI agents, enabling them to store and retrieve memories as markdown files with an SQLite index. The MCP server offers read-only search by default, with optional write tools for manual memory addition and conflict resolution.
    11
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zhangtian-123/codex-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server