@opvoid/codememory 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <img src="assets/Codememory-logo.png" alt="Codememory logo" width="200" />
+</p>
+
+# Codememory
+
+> AI wrote your code. Now it knows what happened.
+
+<p align="center">
+  <video src="assets/Codememory-promo.mp4" controls width="720">
+    Your browser does not support embedded video.
+    <a href="assets/Codememory-promo.mp4">Download the Codememory promo video</a>.
+  </video>
+</p>
+
+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.
+
+## Setup (60 seconds)
+
+```bash
+npm install -g @opvoid/codememory
+codememory init
+```
+
+Then add to your project's `CLAUDE.md`:
+
+```
+@include CODEMEMORY.md
+```
+
+That's it. Claude Code will automatically capture intent when it writes
+code and fetch repair briefs before fixing bugs.
+
+## What `codememory init` creates
+
+- `.mcp.json` — registers Codememory as a Claude Code MCP server (auto-discovered).
+- `CODEMEMORY.md` — rules that tell Claude Code when to call which tool
+  (`capture_intent`, `record_runtime`, `log_failure`, `query_memory`,
+  `get_repair_brief`).
+
+Existing files are preserved by default. Pass `--force` to overwrite.
+
+## 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:
+
+```typescript
+import { RuntimeObserver } from '@opvoid/codememory'
+const observed = observer.observe(yourFunction, 'functionName')
+```
+
+## 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.
+- 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.
+
+## Media
+
+| Asset | Path |
+| ----- | ---- |
+| Logo | [`assets/Codememory-logo.png`](assets/Codememory-logo.png) |
+| Promo video | [`assets/Codememory-promo.mp4`](assets/Codememory-promo.mp4) |
+
+## Examples
+
+See [`examples/`](./examples/) for `basic-capture`, `repair-brief`, and
+`runtime-observer`.
+
+## Development
+
+```bash
+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):
+
+```bash
+pwsh -File scripts/package-source.ps1
+```
+
+Output: [`release/codememory-source.zip`](release/codememory-source.zip)
+
+## License
+
+MIT — byte271

package/examples/basic-capture/index.ts

@@ -0,0 +1,25 @@
+import { CaptureIntentTool } from '../../src/mcp/tools/capture_intent.js';
+import { IntentQueries } from '../../src/store/queries/intent.js';
+import { DatabaseManager } from '../../src/store/database.js';
+
+/**
+ * Example: Capturing AI intent.
+ */
+async function example() {
+  const dbManager = new DatabaseManager('./example.db');
+  const queries = new IntentQueries(dbManager.getDb());
+  const tool = new CaptureIntentTool(queries);
+
+  const result = await tool.execute({
+    prompt: 'Create a function to calculate Fibonacci numbers',
+    generated_code: 'function fib(n) { return n <= 1 ? n : fib(n-1) + fib(n-2); }',
+    file_path: 'math.ts',
+    ai_tool: 'claude_code',
+    language: 'typescript'
+  });
+
+  console.log('Captured Intent:', result);
+  dbManager.close();
+}
+
+example();

package/examples/repair-brief/index.ts

@@ -0,0 +1,43 @@
+import { DatabaseManager } from '../../src/store/database.js';
+import { IntentQueries } from '../../src/store/queries/intent.js';
+import { RuntimeQueries } from '../../src/store/queries/runtime.js';
+import { RepairAssembler } from '../../src/engines/repair/assembler.js';
+import { GetRepairBriefTool } from '../../src/mcp/tools/get_repair_brief.js';
+
+/**
+ * Example: Generating a Repair Brief
+ * This script demonstrates how Codememory assembles context for AI to fix a bug.
+ */
+async function example() {
+  const dbManager = new DatabaseManager('./repair-example.db');
+  const db = dbManager.getDb();
+  
+  const intentQueries = new IntentQueries(db);
+  const runtimeQueries = new RuntimeQueries(db);
+  const assembler = new RepairAssembler(intentQueries, runtimeQueries);
+  const tool = new GetRepairBriefTool(assembler);
+
+  // 1. Setup mock data
+  const memoryId = 'mem-123';
+  db.prepare('INSERT INTO intent_records (id, created_at, file_path, prompt, generated, ai_tool, language) VALUES (?, ?, ?, ?, ?, ?, ?)').run(
+    memoryId, Date.now(), 'api.ts', 'Fetch user data', 'function fetchUser(id) { return {id}; }', 'claude', 'ts'
+  );
+  
+  db.prepare('INSERT INTO runtime_snapshots (id, intent_id, recorded_at, function_name, file_path, success) VALUES (?, ?, ?, ?, ?, ?)').run(
+    'snap-1', memoryId, Date.now(), 'fetchUser', 'api.ts', 1
+  );
+
+  db.prepare('INSERT INTO failures (id, intent_id, snapshot_id, failed_at, error_type, error_message, repair_status) VALUES (?, ?, ?, ?, ?, ?, ?)').run(
+    'fail-1', memoryId, 'snap-1', Date.now(), 'NetworkError', 'Failed to fetch', 'unresolved'
+  );
+
+  // 2. Get the brief
+  const brief = await tool.execute({ failure_id: 'fail-1' });
+  
+  console.log('--- REPAIR BRIEF FOR AI ---');
+  console.log(brief.repair_context);
+  
+  dbManager.close();
+}
+
+example().catch(console.error);

package/examples/runtime-observer/index.ts

@@ -0,0 +1,33 @@
+import { RuntimeObserver } from '../../src/engines/runtime/observer.js';
+import { logger } from '../../src/utils/logger.js';
+
+/**
+ * Example: Explicit Runtime Observation
+ * This script demonstrates how to wrap a function to record its behavior.
+ */
+async function example() {
+  const observer = new RuntimeObserver(
+    'memory-123',
+    async (data) => console.log('RECORDED:', data.function_name, 'Success:', data.success),
+    async (data) => console.log('FAILURE LOGGED:', data.error_message)
+  );
+
+  const add = (a: number, b: number) => {
+    if (a < 0) throw new Error('No negatives!');
+    return a + b;
+  };
+
+  const observedAdd = observer.observe(add, 'add');
+
+  console.log('--- Case 1: Success ---');
+  observedAdd(5, 10);
+
+  console.log('\n--- Case 2: Failure ---');
+  try {
+    observedAdd(-1, 10);
+  } catch (e) {
+    // Error is caught by observer and re-thrown
+  }
+}
+
+example().catch(console.error);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@opvoid/codememory",
+  "version": "0.1.0",
+  "description": "A runtime behavior memory layer for AI-generated code",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "codememory": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/bin.ts --format cjs,esm --dts && pnpm run copy-templates",
+    "copy-templates": "node -e \"const fs=require('fs'),path=require('path');const src=path.resolve('src/templates'),dst=path.resolve('dist/templates');fs.mkdirSync(dst,{recursive:true});for(const f of fs.readdirSync(src))fs.copyFileSync(path.join(src,f),path.join(dst,f));console.log('Copied templates ->',dst)\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "ci": "pnpm run check:brand && pnpm run typecheck && pnpm run lint && pnpm test && pnpm run build",
+    "check:brand": "node scripts/check-brand.js",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "postinstall": "node -e \"try{require('better-sqlite3')}catch(e){console.log('Rebuilding better-sqlite3...');require('child_process').execSync('pnpm rebuild better-sqlite3',{stdio:'inherit'})}\""
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "memory",
+    "runtime",
+    "behavior"
+  ],
+  "author": "byte271",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "better-sqlite3": "^11.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.10",
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.5.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}