Codememory

AI wrote your code. Now it knows what happened.

AI-generated code breaks. The agent doesn't remember why it wrote what it wrote, what the function actually did at runtime, or what fixed the bug last time the same shape of failure showed up. So you and the agent end up in a loop — generate, break, guess, regenerate. Codememory is the memory layer that breaks the loop. It records behavioral memory of your code: the intent behind each generation, what executed at runtime, where it failed, and what fix worked. The next time the agent touches that code, it gets a repair brief instead of a blank slate.

Why Codememory beats agentmemory

| | agentmemory | Codememory | | -------------------------------------------- | -------------------- | ----------------------------------------------- | | Stores | Conversation history | Code behavior history | | Knows why code broke | ✗ | ✓ | | Runtime awareness | ✗ | ✓ | | Repair brief | ✗ | ✓ — intent + code + trace + fix approach | | Works without changes to your workflow | ✓ | ✓ |

How it works

When the agent writes code, Codememory captures the intent (the prompt, the file, a content hash) via an MCP tool call. At runtime an observer records what each instrumented function actually did — inputs, outputs, errors, stack traces — and links those traces back to the originating intent. When something fails or the agent revisits the same code, Codememory returns a repair brief that fuses intent + runtime + failure + a suggested fix approach so the next edit is informed instead of speculative.

Codememory goes beyond passive memory — it actively guards against reintroducing known bugs (proactive guardrails), auto-heals failures by generating patches from historical memory (autonomous self-repair), and cross-references learnings from all your projects (cross-project knowledge graph). A built-in web dashboard visualizes the full lifecycle of your code. And with the LAN Relay, your entire team's Codememory instances automatically share fixes and guard rules — no cloud, no setup, just encrypted peer-to-peer knowledge sharing.

Setup (60 seconds)

npm install -g @opvoid/codememory
codememory init

Then add to your project's agent rules file:

# Claude Code: add to CLAUDE.md
# Cursor / Windsurf: add to .cursorrules or .windsurfrules
# Codex: add to CODEX.md

@include CODEMEMORY.md

That's it. Your AI agent will automatically capture intent when it writes code and fetch repair briefs before fixing bugs.

What codememory init creates

• .mcp.json — registers Codememory as an MCP server for your provider (Claude Code, Cursor, Codex, or Windsurf).
• CODEMEMORY.md — rules that tell the AI agent when to call which tool: all 14 MCP tools covering capture, runtime, failure, resolution, query, repair, lineage, auto-heal, guardrails, cross-project search, and LAN relay sharing.

Existing files are preserved by default. Pass --force to overwrite.

CLI commands

| Command | What it does | |---------|-------------| | codememory init | Scaffold .mcp.json + CODEMEMORY.md for your provider | | codememory init --provider cursor | Scaffold for Cursor, Codex, or Windsurf instead of Claude Code | | codememory init --force | Overwrite existing config and rules files | | codememory | Start the MCP server (with auto-heal worker + optional dashboard) | | codememory dashboard | Start the Behavioral Time Machine web UI standalone | | codememory heal | Manually trigger auto-healing for all unresolved failures | | codememory relay start | Enable LAN relay for team intelligence sharing | | codememory relay pair | Display your pairing key for team setup | | codememory peers | List all active Codememory instances on your LAN | | codememory sync --force | Manually pull collective wisdom from peers | | codememory --version | Print the version | | codememory --help | Print available commands |

Configuration

All configuration is via environment variables. None are required — everything has sensible defaults.

| Variable | Default | Description | |----------|---------|-------------| | CODEMEMORY_AUTOHEAL_ENABLED | true | Enable background auto-heal worker | | CODEMEMORY_AUTOHEAL_POLL_MS | 30000 | Worker polling interval in milliseconds | | CODEMEMORY_AUTOHEAL_MAX_CONCURRENT | 3 | Max concurrent auto-heal tasks | | CODEMEMORY_DASHBOARD_ENABLED | false | Enable the web dashboard (opt-in) | | CODEMEMORY_DASHBOARD_PORT | 4210 | Dashboard HTTP port | | CODEMEMORY_GUARD_CONFIDENCE_THRESHOLD | 0.3 | Minimum confidence to surface guard warnings | | CODEMEMORY_RELAY_ENABLED | false | Enable LAN relay and team sharing (opt-in) | | CODEMEMORY_RELAY_PORT | 4211 | Relay WebSocket port | | CODEMEMORY_RELAY_PAIRING_KEY | auto-generated | Pre-shared encryption key for team peers | | CODEMEMORY_MAX_SNAPSHOTS_PER_INTENT | 100 | Max runtime snapshots retained per intent | | LOG_LEVEL | info | Log verbosity (trace/debug/info/warn/error) |

CJS vs ESM

CJS projects: automatic instrumentation via a Module._load require hook. Call hook.start() and local require(...) calls are auto-instrumented.

ESM projects: Node does not expose a comparable hook, so use the manual observer API:

import { RuntimeObserver } from '@opvoid/codememory'
const observed = observer.observe(yourFunction, 'functionName')

The MCP tools (all 14)

| Tool | Purpose | |------|---------| | capture_intent | Record the intent behind generated code (returns a stable memory_id). Idempotent — re-capturing the same intent returns duplicate: true. | | record_runtime | Record an observed function execution (args, return value, duration). | | log_failure | Record an error tied to a memory_id. Validates snapshots belong to the intent. | | log_resolution | Link a resolved failure to the fixing intent (provenance). | | query_memory | Search intents via FTS5 natural-language search (keyword/semantic) or filtered query (file_path, status, since). Returns true pagination totals. | | get_repair_brief | Assemble a structured repair context: intent + runtime traces + failures + proven fixes from similar past errors. | | get_code_lineage | Trace the full generational history of code (parent → child → grandchild chains). | | auto_heal_trigger | v0.3 — Trigger autonomous self-repair for a logged failure; generates a patch from historical memory. | | auto_heal_status | v0.3 — Check the status of an auto-heal task (pending/running/completed/failed). | | predict_issue | v0.3 — Proactive guardrails: check proposed code BEFORE writing to prevent re-introducing known bugs. | | cross_project_search | v0.3 — Search failures and proven fixes across ALL your Codememory projects. | | relay_status | v0.3.5 — Check LAN relay status: connected peers, shared briefs, pairing fingerprint. | | share_brief | v0.3.5 — Share a repair brief with the team via encrypted LAN relay. | | broadcast_rule | v0.3.5 — Broadcast a guard rule to all team peers for collective immunity. |

The repair brief

When something breaks, instead of asking the AI to guess, Codememory gives it:

• The original intent behind the code (prompt, file, content hash).
• What the code actually did at runtime (inputs, outputs, side effects).
• The exact failure point and stack trace.
• Proven fixes from similar past errors (same error type, previously resolved).
• A suggested fix approach chosen by error type and prior outcomes.

That brief is fetched through one MCP tool call, before any edit, so the agent stops re-deriving context that was already paid for once.

Autonomous self-healing

When a failure is logged, Codememory's auto-heal worker (background thread) polls for unresolved failures and automatically generates repair patches from historical memory. Each patch is a comment-annotated diff built from proven fixes that resolved the same shape of failure before.

The agent can trigger healing explicitly via auto_heal_trigger or let the background worker handle it. Either way, auto_heal_status reports the task state and the generated patch when ready.

Proactive guardrails

Before AI writes a single line, predict_issue checks the proposed approach against all known failure patterns — both in the current project and across any other project sharing the Codememory database. It returns warnings with confidence levels and risk assessment. This flips the script from post-mortem bug-fixing to preemptive bug-prevention.

Guard rules are learned automatically: when a failure is resolved, the resolution's approach and context are distilled into a reusable rule that fires on any future code matching the same pattern.

Cross-project knowledge graph

Codememory explicitly models your projects (projects table). Intents link to their parent project. When you call cross_project_search, it finds failures and proven fixes across every project you've registered — meaning a bug you fixed once in one repo never needs to be rediscovered in another. Guard rules learned in Project A automatically apply to Project B.

Behavioral Time Machine (dashboard)

codememory dashboard

A zero-dependency, single-file HTML dashboard served on localhost:4210 visualizes the full lifecycle of your code:

• Error rate trends — 90-day rolling window with moving averages
• Fix effectiveness — which fix approaches succeed most often
• Event timeline — chronological view with filtering tabs (intents, failures, resolutions, runtime snapshots)
• Dark-themed, auto-refreshing, no external CDN dependencies

All data is local. Nothing leaves your machine.

LAN Relay — Team Neural Link (v0.3.5)

export CODEMEMORY_RELAY_ENABLED=true
codememory relay start

Codememory instances on the same local network automatically discover each other via mDNS and share knowledge through encrypted WebSocket connections. When one developer fixes a bug, every teammate's AI agent learns from it.

• Zero-config discovery: mDNS automatically finds peers — no IP addresses, no servers, no cloud.
• End-to-end encryption: AES-256-GCM with a pre-shared pairing key. Your code's runtime behavior never leaves your local network.
• Collective guardrails: When you create a guard rule for a dangerous pattern, it's instantly broadcast to every peer. One person hits a wall, the whole team gets the map.
• Hive Mind dashboard: The dashboard gains a team view showing connected peers, shared briefs, and a contribution heatmap.

Run codememory relay pair to display your pairing key for teammates, and codememory peers to see who's online.

Media

| Asset | Path | | ----- | ---- | | Logo | assets/Codememory-logo.png | | Promo video | assets/Codememory-promo.mp4 |

Examples

See examples/ for basic-capture, repair-brief, and runtime-observer. These are reference implementations for local development — they import from src/ and are not shipped in the npm package.

Development

pnpm install
pnpm run ci          # typecheck + lint + test + build

Public source archive

To produce a clean ZIP suitable for public distribution (no node_modules, build output, or local databases):

pwsh -File scripts/package-source.ps1

Output: release/codememory-source.zip

License

MIT — byte271