Agent-Memory-Bridge: Instructions file for Codex

Agent Memory Bridge Contributor Instructions

These instructions are self-contained. Contributors only need this repository, Python, and the documented toolchain; no external profile, memory service, or machine-specific setup is required.

Setup And Checks

• Use Python 3.11 or newer.
• Install dev dependencies from the repo root:

python -m venv .venv
python -m pip install -e ".[dev]"

• Run the main test suite:

python -m pytest

• Run lint and format checks:

ruff check src tests scripts
ruff format --check src tests scripts

• Run the Linux CI typecheck target. On Windows, add --platform linux so mypy checks the same platform contract as CI instead of rejecting POSIX-only process APIs during local analysis:

mypy src/agent_mem_bridge/schema.py src/agent_mem_bridge/storage.py src/agent_mem_bridge/provenance.py src/agent_mem_bridge/repository.py src/agent_mem_bridge/signals.py src/agent_mem_bridge/query.py src/agent_mem_bridge/state_io.py src/agent_mem_bridge/command_provider.py src/agent_mem_bridge/database_maintenance.py src/agent_mem_bridge/release_contract.py src/agent_mem_bridge/run_ledger.py src/agent_mem_bridge/run_outcome_authority.py src/agent_mem_bridge/run_projection.py src/agent_mem_bridge/run_consolidation.py src/agent_mem_bridge/server.py src/agent_mem_bridge/mcp_boundary.py src/agent_mem_bridge/stdio_probe.py

• For release-facing or public-surface changes, also run:

python ./scripts/run_benchmark.py
python ./scripts/run_deterministic_proof.py
python ./scripts/check_release_contract.py
python ./scripts/check_public_surface.py
python ./scripts/check_onboarding_contract.py

Architecture Boundaries

• Runtime code lives in src/agent_mem_bridge; tests live in tests; proof and regression fixtures live in benchmark; operational entry points live in scripts.
• server.py defines the public MCP surface. Keep the tool contract small and explicit: store, recall, browse, stats, forget, feedback, promote, annotate, revise, export, begin_run, record_run_event, get_run, complete_run, claim_signal, extend_signal_lease, and ack_signal.
• storage.py, repository.py, and schema.py own durable record behavior. signals.py owns Signal lifecycle rules. query.py and index modules own retrieval and derived indexes.
• CLI reports, review queues, Task Briefs, activation receipts, benchmarks, and context assembly are not separate public MCP tools unless a reviewed contract change explicitly adds them.
• Worker execution, hosted identity, OAuth, general per-namespace ACLs, sandboxing, remote multi-user coordination, and distributed locking are outside the core bridge boundary unless the implementation and public docs both change.