Give an agent continuity without teaching it to trust guesses.

Website · Install · Connect an agent · Beta 4.0 · Roadmap · Changelog

---

MemCoder is a local cognition layer for coding agents. It remembers verified work, retrieves only what can change the next decision, and declines to learn when the host cannot prove an outcome.

It is not a transcript archive and it is not another model. The agent still reasons, edits, and uses tools. MemCoder supplies a small evidence-backed brief, tracks what influenced the task, and admits durable learning only after QA.

The invariant: no proof, no durable learning.

Why it exists

Most agent memory systems optimize for recall. MemCoder optimizes for useful, applicable recall—and for knowing when to stay quiet.

The usual failure	MemCoder's response
Similar history floods the prompt	Compile the minimum context needed for this decision
An old fix is mistaken for current proof	Preserve applicability limits and require present-day verification
A successful task rewrites memory automatically	Separate outcome, influence, and proof; ambiguous credit stays uncertain
Slow retrieval blocks the agent	Return the best completed result by a hard deadline, or fail open
Self-improvement silently changes trusted behavior	Keep Dreams, simulations, patterns, and Skill revisions as candidates until evidence and approval exist

Install

MemCoder supports Python 3.10 and newer.

From PyPI

python -m pip install --pre --upgrade memcoder
memcoder setup --all
memcoder doctor

That is enough for the provider-free Core. No generation model, cloud account, CUDA installation, Ollama service, or API key is required.

From source

Use this when the repository is newer than the published beta:

git clone https://github.com/Shikhar-code/memcoder.git
cd memcoder
python -m pip install --no-build-isolation .
python -m memcoder doctor

Confirm the installed surface:

memcoder --help
memcoder storage status
memcoder host-manifest --host codex

The 60-second model

task starts
    ↓
attention gate ── irrelevant / empty / slow ──→ return nothing; host continues
    ↓
lexical evidence first ──→ optional warm semantic refinement
    ↓
minimum-sufficient brief + explicit proof obligation
    ↓
host works and verifies
    ↓
outcome receipt → causal credit → admitted memory → candidate learning

MemCoder works at lifecycle boundaries. It does not narrate continuously over the host, and it does not need a complex MemCoder-specific prompt.

Boundary	Automatic behavior	Safety boundary
Task start	Detect risk, retrieve quickly, compile a brief, or abstain	Retrieved memory is guidance, never proof
Before a risky action	Surface a known failure frontier and cheapest preventive check	Unchanged requests are deduplicated
Verification	Inspect host-supplied tests, builds, assertions, diagnostics, or review	A confident answer is not evidence
Task close	Record an admitted experience and queue causal credit, competence, private-pattern, and deep-Dream work	Host completion stays fast; derived candidates remain untrusted

Persistent MCP and Studio hosts resume the durable queue automatically. A one-shot CLI process leaves unfinished work queued for the next persistent session. Inspect it with '{"action":"status"}' | memcoder derived-cognition --input -, or replace status with drain for an explicit bounded drain.

Minimal lifecycle example

Start:

{
  "event": "task_started",
  "task_id": "billing-validation-42",
  "problem": "Fix request validation without changing successful responses.",
  "agent_id": "billing-api",
  "environment": {"project_id": "billing", "branch": "main"}
}

memcoder autopilot --input task-start.json

Finish with real evidence:

{
  "event": "verification_finished",
  "task_id": "billing-validation-42",
  "problem": "Fix request validation without changing successful responses.",
  "agent_id": "billing-api",
  "outcome": {
    "guidance_used": true,
    "changed_action": true,
    "verification_passed": true,
    "files": ["validation.py"],
    "summary": "Required values are checked before normalization.",
    "solution": "Added one validation guard and preserved valid requests.",
    "evidence": {"checks": [{
      "name": "validation regression",
      "kind": "test",
      "status": "passed",
      "command": "python tests/test_validation.py",
      "output": "PASS"
    }]}
  }
}

memcoder autopilot --input task-finish.json

Beta 4.0

Beta 4 moves MemCoder from a reliable memory runtime to a bounded cognition runtime. The new layers are provider-free, local, additive, and reversible.

Fast enough to disappear

• Anytime scheduler — lexical evidence arrives first; a warm semantic path may replace it only when it finishes in budget and clearly improves utility.
• Risk-adaptive compute — low-risk tasks receive less work; high-risk tasks receive more retrieval, failure-frontier, and verification budget.
• Privacy-safe latency traces — phase timing, timeout rate, backend, and critical path are observable without retaining prompt or repository content.
• Minimum-sufficient context — the host receives a compact decision and proof packet. Stable handles make deeper evidence an explicit request.

Better hypotheses, stricter promotion

• Bounded simulation predicts assumptions, hazards, falsifiers, and expected observations without executing commands or mutating trusted memory.
• Deep Dreaming searches counterexamples and requires held-out evidence plus explicit approval before a candidate can become a Principle.
• Immutable Skill revisions propose a next version beside the current one; verification, promotion, credit, and rollback retain their lineage.
• Private cross-project patterns require approved evidence from at least two projects and store opaque references rather than raw cross-project content.

Evidence that survives time

• Causal credit graph connects intervention, evidence, action, outcome, and verification while preserving uncertain attribution.
• Verified competence derives long-lived skill and task-family confidence only from admitted evidence, with stale and review-required states.
• Cognitive Git binds hypotheses and proof obligations to host-supplied Git context; drift blocks a merge until the proof is rerun.

These features do not claim human cognition. They make agent continuity more selective, testable, and difficult to corrupt.

What is durable

Stored object	Meaning
Experience	Verified task, environment, action, affected files, and result
Reflection	Observation grounded in an approved Experience
Mistake / Failure Frontier	Verified failure mechanism and preventive check
Principle	Transferable guidance with evidence and applicability limits
Skill	Versioned procedure with preconditions, proof, failure handling, and rollback
Project state	Decisions, rationale, constraints, risks, open loops, and next actions

Checkpoints, receipts, simulations, Dream candidates, Skill revisions, and private pattern candidates live beside semantic memory. Their presence does not make them trusted or automatically retrievable.

Connect your agent

Host	Setup	Verification
Codex Desktop	Install the local MemCoder marketplace plugin	memcoder doctor --host codex
AGY / Antigravity	memcoder setup-agy	memcoder doctor --host agy
Claude Code	Run memcoder setup-claude inside the project	memcoder doctor --host claude
Any MCP host	Run python -m adapters.mcp.server	memcoder host-manifest --host <name>

Codex Desktop

From a source checkout:

python scripts/configure_codex_plugin.py
codex plugin marketplace add .\codex-marketplace
codex plugin add memcoder@memcoder-local

On Windows, the configuration helper records the current interpreter in local MemCoder user data, so Codex Desktop does not need to inherit an activated Conda environment or a python entry on PATH.

Restart Codex and begin a new development task. The bundled Skill invokes the lifecycle automatically; the user does not need to ask for MemCoder.

AGY / Antigravity

memcoder setup-agy
memcoder doctor --host agy

See the AGY integration guide.

Claude Code

memcoder setup-claude
memcoder doctor --host claude

Setup preserves existing project instructions and MCP servers. See the Claude Code guide.

Use the Beta 4 surfaces

Every advanced operation accepts a JSON request through the CLI and has a matching Python, MCP, and localhost-service surface.

memcoder autopilot        automatic lifecycle entry point
memcoder context          compile or explicitly expand minimum context
memcoder simulate         run or inspect a non-executing simulation
memcoder causal           inspect causal traces and conservative credit
memcoder dream            run, verify, approve, reject, or roll back Dreams
memcoder skill-revision   propose and prove immutable Skill versions
memcoder competence       derive or inspect verified competence
memcoder pattern          discover private cross-project candidates
memcoder derived-cognition inspect, resume, or drain queued local cognition
memcoder branch           proof-gated cognition with optional Git context
memcoder retrieval-debug  explain ranking, gates, and abstention
memcoder storage          status, migrate, export, back up, or restore

Example: compile a 300-token context packet.

{
  "action": "compile",
  "problem": "Safely change tenant validation.",
  "agent_id": "billing-api",
  "token_budget": 300,
  "environment": {"project_id": "billing"}
}

memcoder context --input context.json

Run memcoder <command> --help for exact input requirements.

Trust boundary

• No proof, no durable learning. Deterministic QA admits memory.
• Similarity is not applicability. Related evidence may be withheld.
• Guidance is not authority. The current host verifies the current project.
• Ambiguity stays uncertain. A pass does not prove MemCoder caused it.
• Candidates are not memories. Simulation, Dream, revision, and pattern output cannot silently enter trusted retrieval.
• Evidence is preserved. Calibration changes ranking, not history.
• Failure is non-blocking. Timeout, empty storage, and optional backend failure return control to the host.
• Core is local and provider-free. Cloud and external model APIs are not hidden runtime requirements.

Memory Studio

Use the packaged browser Studio:

memcoder studio

Open http://127.0.0.1:8765. Studio shows memories, evidence, host receipts, outcomes, policy, replay, and—when data exists—Beta 4 cognition signals.

The repository also contains a lightweight Tauri desktop shell using plain HTML, CSS, and JavaScript against the same Python Core:

cd studio
bun install
bun run dev

Build the Windows installer with bun run build:exe. The NSIS output is under studio/src-tauri/target/release/bundle/nsis/.

Operations

memcoder benchmark --iterations 5
memcoder storage upgrade --dry-run
memcoder storage backup
memcoder storage upgrade

Storage upgrades are additive and byte-safe: MemCoder creates a SQLite rollback copy, applies the lexical and causal extensions, validates schema and record count, and restores the copy on failure. JSON and ZIP snapshots include Beta 4 sidecars without deleting newer local history during restore.

For host budgets, set MEMCODER_INTERVENTION_TIMEOUT_MS (default 1500 ms). MEMCODER_CIRCUIT_COOLDOWN_SECONDS controls timeout cooldown, and MEMCODER_EMBED_CACHE_SIZE bounds the in-process embedding cache. Values are clamped to safe ranges.

Evidence without theatre

MemCoder has two narrow controlled results. In the original transfer study, three baseline AGY runs passed the visible test but failed private robustness checks; six assisted runs passed those same private checks. The Beta 4 harness then passed 24 matched intervention-decision tasks with 100% retrieval precision, 100% correct abstention, no harmful transfer, and no host-blocking failures. These results support transfer in their controlled setups—not a universal improvement claim.

Provider independence, retrieval safety, QA admission, lifecycle idempotence, host parity, abstention, timeout cleanup, candidate proof gates, causal storage, and rollback have deterministic coverage. Independent end-to-end coding uplift, developer rework, and production-scale latency remain evaluation targets.

• Controlled transfer result
• Beta 4 controlled evaluation
• Evaluation protocol
• Real-project evaluation protocol

Current non-goals:

• no claim of consciousness or human-equivalent cognition;
• no silent self-modification of trusted memory;
• no required cloud account or hosted model in Core;
• no team or multi-agent shared memory in Beta 4.0; and
• no claim that a passing task proves an intervention was helpful.

Development

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

Run the Beta 4 slices first:

python tests/test_beta40_contract.py
python tests/test_beta40_core_slice.py
python tests/test_beta40_higher_cognition.py
python tests/test_beta40_host_certification.py
python tests/test_beta40_release_evaluation.py
python tests/test_beta4_studio_surface.py

Then run the documented provider-free regression pass:

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

Documentation

Document	Purpose
Roadmap	Product sequence, gates, and research direction
Changelog	Version-by-version implementation history
AGY integration	Setup, lifecycle, and certification
Claude Code integration	Project setup and automatic lifecycle
Architecture PDF	Component-level design
Beta 4 controlled evaluation	Reproducible release gates, results, and limitations
Evaluation protocol	Controlled comparison methodology

MemCoder is beta software. Back up local cognition before testing new storage behavior. Reproducible bugs and negative results are welcome through GitHub Issues.

License

MIT © Shikhar-code