Contributing to iai-mcp

Thanks for considering a contribution. This project is small and opinionated. Read this before opening a large PR.

Scope

iai-mcp is a local memory layer for MCP-over-stdio hosts. Contributions that fit the scope:

Bug fixes in capture, recall, consolidation, daemon lifecycle, or the MCP wrapper.
New bench harnesses, or improvements to existing ones.
Documentation fixes and clarifications.
Platform support (Linux, Windows) once the abstractions are ready.
Compatibility with additional MCP-over-stdio hosts (with evidence it was tested end to end).

Contributions outside scope (will likely be declined):

Cloud sync, remote storage, or any network-exposed surface beyond the existing local UNIX socket.
Major architectural rewrites without prior discussion in an issue.
Replacing the three-tier memory model (episodic / semantic / procedural).
Telemetry of any kind.

If you're not sure, open an issue first to discuss before writing code.

Development setup

git clone https://github.com/CodeAbra/iai-mcp.git
cd iai-mcp
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Build the TypeScript MCP wrapper:

cd mcp-wrapper
npm install
npm run build
cd ..

Tests

pytest

A handful of daemon and bridge tests are sensitive to test-pollution and may pass cleanly on a rerun. The harness retries up to twice automatically. If a test fails three times, it's a real failure.

For changes to a specific area, the relevant test files:

Capture: tests/test_capture_*
Recall: tests/test_recall_*
Consolidation: tests/test_consolidation_*, tests/test_sleep_*
Daemon lifecycle: tests/test_daemon_*, tests/test_fsm_*
MCP wrapper: mcp-wrapper/test/

Lint

ruff check src/ tests/
ruff format --check src/ tests/

PRs are expected to pass ruff check clean.

Benchmarks

If your change touches retrieval, capture, or consolidation, include before/after numbers from the relevant bench in the PR description:

python -m bench.verbatim
python -m bench.neural_map
python -m bench.tokens
python -m bench.longmemeval_blind --split S --out /tmp/out.json

Don't tune to the bench. The LongMemEval-S run is blind on purpose.

Commit style

Imperative mood: Fix X, Add Y, not Fixed X or Adding Y.
One logical change per commit.
Keep messages short. One-line subject, body only when motivation is non-obvious.

Pull requests

Small PRs land faster than large ones.
Reference the issue your PR addresses.
Include test coverage for changed behaviour, or explain in the PR description why it isn't applicable.
For retrieval / capture / consolidation changes, include bench re-runs.

The PR template will prompt for the relevant items.

Reporting issues that involve security

Do not open a public issue for anything that looks like a security defect. See SECURITY.md for the private reporting flow.

Code of conduct

By participating, you agree to follow the Code of Conduct.

3 KiB Raw Blame History