codex-agent-mem AGENTS.md

AGENTS

This repository is intentionally optimized for MCP-compatible AI agents, coding workflows, deep-research tools, and maintainers who need a fast map of what exists today.

Public name vs import name

• Public repository name: codex-agent-mem
• Python package import name: codex_agent_mem
• CLI commands use the public name with hyphens, for example codex-agent-mem-smoke

What this project is

• A portable, local-first MCP memory layer for agent continuity across MCP-compatible runtimes
• Current durable store: local SQLite
• Current retrieval surface: MCP stdio
• Current capture path: local agent turn ingestion, including Codex notify on agent-turn-complete
• Current inspection surface: local FastAPI UI at /ui
• Current continuity surface: generated AGENTS.md working-memory block when compression is favorable
• Current extraction strategy: heuristic extraction of session summaries, user requests, objectives, decisions, constraints, pending/completed work, blockers, DoD items, and completion claims

Working rules for agents

• Preserve the local-first MCP core.
• Do not use an operational maintainer database for tests; use temporary databases.
• Keep hosted/web bridge experiments out of the public core unless the repository scope changes explicitly.
• Keep compatibility and token-savings claims tied to reproducible evidence.
• Keep the six README files equivalent in content across languages.
• For broad/container project keys, prefer mem_bootstrap_context or mem_scope_resolve before loading mem_context_pack(project_key). A project-wide pack may remain available, but it must not be treated as the active thread when candidate lanes are ambiguous.
• Do not tag, publish, or release from a dirty tree.

Fastest commands

pip install -e .[dev]
pytest -q
python -m compileall src
ruff check .
python scripts/mcp_contract_smoke.py --both
python scripts/check_repo_hygiene.py
python scripts/smoke_release.py --mcp-subprocess --with-ruff --with-build --with-wheel-smoke
codex-agent-mem-smoke
codex-agent-mem-bootstrap-codex --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db
python -m build