{"_id":"@bambushu/scar","name":"@bambushu/scar","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@bambushu/scar","version":"0.3.0","description":"Failure memory for AI agents - briefing hooks + optional MCP server","type":"module","bin":{"scar":"dist/bin/scar.js","scar-mcp":"dist/bin/scar-mcp.js"},"main":"./dist/core/index.js","exports":{".":"./dist/core/index.js","./mcp":"./dist/mcp/index.js","./adapter":"./dist/adapter/claude-code.js"},"repository":{"type":"git","url":"git+https://github.com/bambushu/scar.git"},"homepage":"https://github.com/bambushu/scar","scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"keywords":["mcp","mcp-server","ai","agents","failure-memory","claude","llm","debugging"],"license":"MIT","engines":{"node":">=22"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","better-sqlite3":"^12.8.0","commander":"^14.0.3","zod":"^3.25.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.13","@types/node":"^22.0.0","tsup":"^8.5.1","typescript":"^5.7.0","vitest":"^3.1.0"},"gitHead":"03fe3763f3e352841e08eb1a4db5161f9325afbb","_id":"@bambushu/scar@0.3.0","bugs":{"url":"https://github.com/bambushu/scar/issues"},"_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-BM6yKlUyoSzl+rLG6LY1UaM+0KNczTUHIP7J/k5hed8H6IGYBiVvenlgmu/f12HInE1oXX1Jih2NKMnUHkqvBw==","shasum":"a5d74ca9662ca1bcadb214da8521b5bfe4e3c115","tarball":"https://registry.npmjs.org/@bambushu/scar/-/scar-0.3.0.tgz","fileCount":34,"unpackedSize":437490,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCNslXzJBOfoFKPxb4j7gF9fDlAHh+VsTM/leIGDAGctgIhAOfenxWdff7Qg4OCnqghRGJg70z7HIbXpX5AISfUOlUa"}]},"_npmUser":{"name":"bambushu","email":"info@mad-it.agency"},"directories":{},"maintainers":[{"name":"bambushu","email":"info@mad-it.agency"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/scar_0.3.0_1777388566765_0.720133153762248"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T15:02:46.697Z","0.3.0":"2026-04-28T15:02:46.976Z","modified":"2026-04-28T15:02:47.179Z"},"maintainers":[{"name":"bambushu","email":"info@mad-it.agency"}],"description":"Failure memory for AI agents - briefing hooks + optional MCP server","homepage":"https://github.com/bambushu/scar","keywords":["mcp","mcp-server","ai","agents","failure-memory","claude","llm","debugging"],"repository":{"type":"git","url":"git+https://github.com/bambushu/scar.git"},"bugs":{"url":"https://github.com/bambushu/scar/issues"},"license":"MIT","readme":"# Scar\n\n> Failure memory for AI agents. Remember what went wrong so you don't repeat it.\n\nScar mines your AI agent's session transcripts for failures, stores them in a local SQLite database, and surfaces a briefing at the start of every new session. Your agent walks into work already aware of what's been broken before.\n\nTwo surfaces:\n- **Hooks** (recommended): SessionStart briefing + Stop-time transcript mining. Passive, automatic, zero agent action required.\n- **MCP server** (optional): Active tools (`scar_log`, `scar_recall`, `scar_context`) for agents that want to query failure history mid-session.\n\nIn practice, the briefing is where most of the value comes from. The MCP layer is for power users who want their agent to actively consult past failures before risky operations.\n\n## Install (slim, recommended)\n\n```bash\nnpm install -g @bambushu/scar\nscar init --claude-code\n```\n\nThat sets up:\n- SQLite database at `~/.cognitive/cognitive.db`\n- SessionStart hook in `~/.claude/settings.json` that runs the briefing\n- Stop hook that mines the just-finished transcript for failures\n\nYou'll see a briefing at the top of every new Claude Code session listing unresolved failure patterns from prior work.\n\n## Install (full, with MCP)\n\nIf you want active lookup tools too:\n\n```bash\nnpm install -g @bambushu/scar\nscar init --claude-code --with-mcp\n```\n\nThis additionally registers the MCP server so Claude Code exposes `scar_log`, `scar_recall`, `scar_context`, etc. as callable tools. Useful if you want your agent to consult Scar before deploys, DB mutations, or other risky ops.\n\n## CLI\n\n```bash\n# Manually log a failure\nscar log -r my-project -l typescript -t bash \\\n  -e \"TypeError: Cannot read properties of undefined\" \\\n  --tried \"Ran test suite\" \\\n  --wrong \"Null access in parser.ts\"\n\n# Query past failures\nscar recall -r my-project -l typescript\n\n# View patterns\nscar stats\nscar stats --stale\n\n# Remove noise\nscar forget <scar-id>\n\n# Export for debugging\nscar export\n```\n\n## MCP Tools (optional install)\n\n| Tool | Purpose |\n|------|---------|\n| `scar_log` | Record a failure with context |\n| `scar_update` | Update a scar - record what worked, change resolution |\n| `scar_recall` | Find relevant past failures |\n| `scar_forget` | Remove a scar |\n| `scar_stats` | Aggregate failure patterns |\n| `scar_context` | Lightweight count of relevant scars (cheap pre-check) |\n\n## How It Works\n\n1. Stop hook fires when a Claude Code session ends, mines the transcript JSONL for Bash/Edit/Write/Read failures, writes them to SQLite\n2. SessionStart hook fires on the next session, reads recent unresolved patterns, prints a briefing into the agent's context\n3. Auto-deduplicates identical errors within 5-minute windows\n4. (Optional, MCP) Agent calls `scar_context` before risky ops or `scar_recall` when investigating a class of error\n\n## Storage\n\nSQLite database at `~/.cognitive/cognitive.db`. Part of a shared cognitive toolkit foundation - future tools (self-trust calibration, intuition/focus) share the same database.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a3e71c62cac368f65add4792548d584c"}