memcoder 0.2.0b1

Start here · How it works · Connect a host · Trust & evidence · Roadmap

MemCoder gives AI agents a durable, local memory loop built on verified work—not chat history. It retrieves relevant evidence, protects memory quality, turns repeated success into reusable Skills, and offers bounded plans without owning your model, tools, or codebase.

Start here

python -m pip install --upgrade memcoder
python -m memcoder --help

That is the entire install. You need Python 3.10+ and internet access the first time MemCoder downloads its local embedding model. You do not need an API key, Ollama, CUDA, or a local generation server.

python -m pip install --no-build-isolation .

What MemCoder does

The boundary is intentional: MemCoder is a cognition layer, not an autonomous coding agent or a replacement for your application database.

How it works

flowchart LR
    T[New task] --> R[Retrieve relevant memory]
    R --> B[Compact brief / bounded plan]
    B --> H[Host agent works]
    H --> V[Host verifies result]
    V --> Q{QA evidence gate}
    Q -->|Approved| E[Experience]
    Q -->|Insufficient or failed| X[Nothing is stored]
    E --> S[Repeated proof → Skill]
    S --> R

Experience → Reflection → Principle → Skill → Plan

1. A host asks for guidance before it starts work.
2. MemCoder returns only trusted, relevant evidence in a compact brief.
3. The host investigates, solves, and independently verifies the task.
4. MemCoder accepts learning only when the supplied evidence passes QA.
5. Repeated verified Experiences can support a reusable Skill.

Use it from any automation

MemCoder works with any host that can run a command or call an MCP tool: AGY / Antigravity CLI, Gemini or Claude scripts, CI jobs, Python applications, and custom agent frameworks.

The universal CLI workflow

1. Ask for guidance

prepare.json

{
  "problem": "Resolve a required-field validation failure and run the focused test.",
  "agent_id": "billing-api",
  "include_shared": false,
  "detail_level": "brief"
}

memcoder prepare --input prepare.json

The response contains a strategy (normal_reasoning, memory_guided, or memory_first), relevant evidence cards, recommended next action, verification requirement, and token budget. Give that response to your host as guidance, not proof.

2. Verify first, then learn

record.json

{
  "task": "Resolved a required-field validation failure.",
  "files": ["src/request_validation.py", "tests/test_request_validation.py"],
  "summary": "The focused test passed after explicit validation was added.",
  "solution": "Validated the required field before processing the request.",
  "evidence": {
    "checks": [{
      "name": "focused request-validation test",
      "kind": "test",
      "status": "passed",
      "command": "python tests/test_request_validation.py",
      "output": "PASS: request validation"
    }]
  },
  "agent_id": "billing-api"
}

memcoder verify --input record.json
memcoder record --input record.json

verify returns approved, rejected, or insufficient_evidence. record re-runs the same gate, so a host cannot pollute memory merely by claiming that a task succeeded.

Use a stable agent_id. It is a local memory namespace, not a provider account. Reuse one label per project—such as billing-api—so unrelated work never mixes.

First task vs. later tasks

Connect a host

AGY / Antigravity CLI

Configure AGY once, then restart it completely:

python -m memcoder setup-agy

MemCoder adds MCP tools such as memcoder_prepare, memcoder_start, memcoder_verify, memcoder_record, memcoder_promote_skill, and memcoder_plan_history.

No agy plugin install, Ollama, API key, or model server is required.

Reliable AGY pattern

For reliable tool use, retrieve in a dedicated first interaction. This keeps host behavior deterministic instead of relying on the model to decide whether to call a tool halfway through a longer prompt.

Do not read, list, edit, or run any files or commands.

Call memcoder_prepare exactly once with:
- problem: "<your exact task>"
- agent_id: "my-project"
- include_shared: false

After the tool returns, print the complete result and stop.

Use the MemCoder guidance returned immediately above as guidance, not proof.
Do not call any more MemCoder tools.

Work only inside the current folder. Do not inspect or edit MemCoder itself.
Solve the requested task, run its focused verification, and report changed
files and complete test output.

After the host verifies success, call memcoder_verify with the actual evidence. Call memcoder_record once only when QA approves it. The reusable AGY prompt template adds stricter guardrails for production use.

python -c "from adapters.mcp.server import mcp; print('MemCoder MCP import OK')"

Python and custom hosts

The CLI is JSON in / JSON out and is the simplest integration point for any host language. Python hosts can also use the public API directly. MCP-capable hosts use the same underlying cognition flow through tool calls.

See MCP integration notes and the CLI help for the complete command surface:

memcoder --help

Skills and plans

Skills make memory procedural. They are not free-form notes and they do not execute commands themselves.

Promote a reusable procedure:

memcoder skill promote --input skill.json

Retrieve a compact brief and bounded plan in one call:

memcoder start --input plan.json

When no matching Skill exists, MemCoder says so and returns a transparent foundation plan—it does not pretend to know a procedure it has not learned.

{
  "name": "Required field validation",
  "when_to_use": "A required request field may be absent before processing.",
  "inputs": ["request payload", "required field name"],
  "steps": [
    "Validate presence and type before string operations.",
    "Raise the expected validation error.",
    "Normalize only after validation.",
    "Run the focused test."
  ],
  "verification": ["The focused validation test passes."],
  "supporting_experience_ids": ["experience-id-one", "experience-id-two"],
  "agent_id": "billing-api"
}

Bring in project instructions

MemCoder can bootstrap project-specific guidance from an AGENTS.md, runbook, or architecture document. It extracts actionable items as candidate Principles; it does not treat documentation as lived Experience.

Preview first, approve second:

{
  "file_path": "AGENTS.md",
  "agent_id": "billing-api",
  "approve": false
}

Use approve: true only after reviewing the candidates. Files must be UTF-8 Markdown inside the launched project and no larger than 1 MB. Code blocks, placeholders, descriptions, and common prompt-injection patterns are rejected.

Trust and evidence

MemCoder is intentionally conservative:

• Local by default: memory lives in ChromaDB on your machine.
• Owner-scoped: records are separated by agent_id and never shared by default.
• Evidence-gated: failed or incomplete verification creates no durable Experience.
• Retrieval-gated: weak and irrelevant memories are filtered before injection.
• Auditable: Skills, reflections, plans, and outcome health retain provenance.

Set MEMCODER_DB_PATH before running MemCoder to use an isolated local database.

What the current evidence says

In the controlled transfer evaluation, three baseline AGY runs passed visible tests but failed private robustness checks. Six valid MemCoder-assisted runs passed the same private checks. That supports a narrow claim: verified validation procedures transferred to unseen variants in this setup.

It does not prove universal coding improvement. Read the full methodology and results, the evaluation protocol, and the real-project evaluation protocol.

Project documentation

Contributing

Run the provider-free checks from a local checkout:

python tests/test_automation_cli.py
python tests/test_mcp_provider_independence.py
python tests/test_retrieval_safety.py
python tests/test_memory_quality.py
python tests/test_qa_admission.py
python tests/test_cognition_brief.py
python tests/test_skill_promotion.py
python tests/test_planning.py
python tests/test_skill_health.py
python tests/test_evaluation.py

Optional legacy Ollama helpers

The old solve() and learn() helpers are outside the provider-free workflow. Install them only if you intentionally need them:

python -m pip install "memcoder[ollama]"

License

MemCoder is released under the MIT License.