memcoder 0.3.0b1

Persistent cognition for agents that need to be right twice.

MemCoder is a local, provider-independent trust layer for coding agents. It retrieves verified context only when it can change a decision, then learns only after the host supplies proof.

_{Local-first · evidence-gated · fail-open · token-aware · host-agnostic}

Start here  ·  Why MemCoder  ·  Beta 3.0  ·  Connect a host  ·  Evidence

Most agent memory systems remember text. MemCoder remembers what was verified, why it mattered, and when it should stay silent.

Why MemCoder

Coding agents lose the thread across long projects. They repeat known mistakes, re-read too much context, and can mistake a plausible answer for a proven one. MemCoder sits beside the host model rather than replacing it:

This means a host can keep working normally when MemCoder has nothing useful to add—or when MemCoder is temporarily unavailable.

The loop

Start here

Install the published package

Use this path after the Beta 3 package is published to PyPI. Until then, use the current-source install below; PyPI may still resolve an earlier beta.

python -m pip install --pre memcoder
python -m memcoder setup
python -m memcoder doctor
python -m memcoder --help
python -m memcoder storage status

MemCoder requires Python 3.10+. Its core does not require Ollama, CUDA, or a generation-model API key. The first semantic-index use may download a local embedding model.

Use the current Beta 3.0 source

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

Give a host one automatic entry point

Create task.json:

{
  "event": "task_started",
  "task_id": "billing-validation-42",
  "problem": "Fix request validation without changing successful responses.",
  "agent_id": "billing-api",
  "environment": {
    "branch": "main",
    "available_checks": ["python tests/test_validation.py"]
  }
}

memcoder autopilot --input task.json

The response is deliberately small: none, risk, brief, or plan, plus the cheapest verification requirement. The host remains in control.

What is in the current core

What's new in Beta 3.0

Beta 3.0 makes the local cognition engine inspectable and controllable without requiring a provider, cloud account, or raw storage access. It adds a Memory Firewall, deterministic replay, portable cognition capsules, an append-only host event journal, and a small localhost service for automatic adapters.

host adapter -> local service -> policy check -> cognition -> verification receipt
                                      \-> replay / capsule / Studio APIs

All new surfaces fail open for host work, keep imported cognition untrusted until verified, and remain local by default.

Lightweight desktop Studio

Beta 3 also includes a native Tauri shell in studio/. It has no frontend framework, charting package, cloud dependency, or duplicated memory engine. The Python Core remains the source of truth and the shell talks to its localhost service.

From a fresh PowerShell session in the repository:

cd studio
bun install

# Optional when `memcoder` is not on PATH:
$env:MEMCODER_PYTHON = "C:\path\to\your\python.exe"

bun run dev

Requirements for the desktop shell are Python 3.10+, an installed MemCoder environment, Bun, and the Windows Tauri prerequisites (Rust/MSVC and WebView2). The browser fallback does not require Tauri:

memcoder studio

To create the Windows installer from the repository:

cd studio
bun install
bun run build:exe

The installer is written to studio/src-tauri/target/release/bundle/nsis/. The generated setup file is named MemCoder Studio_0.3.0_x64-setup.exe.

The desktop shell starts memcoder service serve when the command is available. If it cannot find the command, run this once in another terminal and press Retry connection in Studio:

memcoder service serve

The app exposes useful local views for Overview, Memories, Evidence, Replay Lab, Dreaming, and Policy. It intentionally avoids decorative graphs and raw chat transcripts.

On a new installation, open Evidence or Dreaming and select Load Guided Demo. This creates two isolated, QA-approved example memories and their lifecycle evidence under studio-demo. It is safe to repeat and does not touch your real project memories. In Dreaming, Find New Connections compares verified memories for the selected Memory Scope and creates only an untrusted candidate; it never promotes a memory automatically.

The service endpoints are also available to other hosts:

GET  /v1/summary
GET  /v1/records?q=validation&limit=50
GET  /v1/records/<record_id>
GET  /v1/events
GET  /v1/dreams
GET  /v1/replays
GET  /v1/policy
POST /v1/policy/check
POST /v1/policy/save
POST /v1/policy/retrieval
POST /v1/policy/export
POST /v1/replay
POST /v1/capsule
POST /v1/demo
POST /v1/dream
POST /v1/storage/backup
POST /v1/storage/export

The service binds to 127.0.0.1 by default. No model provider, Ollama, CUDA, API key, or cloud account is required for this local product slice.

What's new in Beta 2.6

Beta 2.6 turns verified failures and competing ideas into inspectable, reversible cognition. It stays local and provider-free: the host still reasons, edits, and verifies while MemCoder supplies bounded evidence and proof gates.

failure evidence -> Failure Frontier -> warning + smallest check
alternative idea -> Cognitive Branch -> proof obligations -> diff -> merge/rollback
intervention outcome -> calibration summary -> safer future ranking

What's new in Beta 2.5

Beta 2.5 is the preceding foundation release. It adds a controlled way for memory to improve between verified tasks without turning “self-improvement” into silent, unreviewable behavior.

verified outcome
  -> automatic Dream candidate
  -> sandbox evidence
  -> promoted Principle or rejected candidate
  -> reversible provenance-backed learning

Connect a host

Codex Desktop

The included MemCoder Codex plugin invokes the lifecycle automatically for substantive engineering work. You do not need to write a MemCoder-specific prompt every time.

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

In Codex, add codex-marketplace as a local marketplace, install MemCoder, then restart Codex. After source updates, refresh/reinstall the MemCoder plugin so Codex loads its latest skill instructions.

AGY / Antigravity

python -m memcoder setup-agy

Restart AGY. The AGY prompt template explains the manual path; the MCP adapter remains provider-free.

Python, MCP, and automation

Every operation is available through structured Python, CLI, and MCP calls.

from memcoder import autopilot_event_cognition

packet = autopilot_event_cognition(
    event="task_started",
    task_id="task-42",
    problem="Fix request validation safely.",
    agent_id="billing-api",
)

Evidence, not hype

MemCoder has a controlled transfer result: three baseline AGY runs passed the visible test but failed private robustness checks; six MemCoder-assisted runs passed the same private checks. That supports a narrow claim that verified validation procedures transferred to unseen variants in that setup.

It does not prove that MemCoder universally improves every model, task, or repository. Beta 2.5’s automatic Dreaming, sandbox, rollback, contract, and host-certification behavior, plus Beta 2.6’s frontier and branch gates, are verified provider-free. A clean real-host baseline-versus-Dreaming comparison is deferred to the 1.0 evidence gate.

• Controlled transfer result
• Evaluation protocol
• Real-project evaluation protocol

Developer reference

memcoder intervene --input task.json
memcoder verify --input outcome.json
memcoder record --input outcome.json
memcoder retrieval-debug --input task.json
memcoder storage status

memcoder project-update --input project-update.json
memcoder project-resurrect --input project-resurrect.json
memcoder project-handoff --input project-handoff.json
memcoder project-accept --input project-accept.json

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
python tests/test_dreaming.py
python tests/test_cognition_contracts.py
python tests/test_beta25_cli.py

Explore further

License

Released under the MIT License.