{"id":50897715,"url":"https://github.com/Dicklesworthstone/cass_memory_system","last_synced_at":"2026-07-03T16:01:20.182Z","repository":{"id":328463262,"uuid":"1111896892","full_name":"Dicklesworthstone/cass_memory_system","owner":"Dicklesworthstone","description":"Procedural memory for AI coding agents: transforms scattered session history into persistent, cross-agent memory so every agent learns from every other","archived":false,"fork":false,"pushed_at":"2026-06-30T00:13:54.000Z","size":3254,"stargazers_count":390,"open_issues_count":0,"forks_count":47,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-30T02:12:32.149Z","etag":null,"topics":["ai-agents","bun","developer-tools","memory","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dicklesworthstone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-07T20:45:32.000Z","updated_at":"2026-06-30T00:13:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Dicklesworthstone/cass_memory_system","commit_stats":null,"previous_names":["dicklesworthstone/cass_memory_system"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/Dicklesworthstone/cass_memory_system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fcass_memory_system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fcass_memory_system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fcass_memory_system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fcass_memory_system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dicklesworthstone","download_url":"https://codeload.github.com/Dicklesworthstone/cass_memory_system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fcass_memory_system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35092185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","developer-tools","memory","typescript"],"created_at":"2026-06-16T01:31:30.076Z","updated_at":"2026-07-03T16:01:20.171Z","avatar_url":"https://github.com/Dicklesworthstone.png","language":"TypeScript","funding_links":[],"categories":["ai-agents"],"sub_categories":[],"readme":"# cass-memory\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"cm_illustration.webp\" alt=\"cass-memory - Procedural memory for AI coding agents\"\u003e\n\u003c/div\u003e\n\n![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)\n![Runtime](https://img.shields.io/badge/runtime-Bun-f472b6.svg)\n![Status](https://img.shields.io/badge/status-alpha-purple.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n\n**Procedural memory for AI coding agents.**\nTransforms scattered agent sessions into persistent, cross-agent memory—so every agent learns from every other agent's experience.\n\n\u003cdiv align=\"center\"\u003e\n\n**One-liner install (Linux/macOS):**\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh?$(date +%s)\" \\\n  | bash -s -- --easy-mode --verify\n```\n\n**Or via package managers:**\n\n```bash\n# macOS/Linux (Homebrew)\nbrew install dicklesworthstone/tap/cm\n\n# Windows (Scoop)\nscoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket\nscoop install dicklesworthstone/cm\n```\n\n\u003c/div\u003e\n\n---\n\n## 🤖 Agent Quickstart (JSON)\n\n**Always use `--json` in agent contexts.** stdout = data, stderr = diagnostics, exit 0 = success.\n\n```bash\n# 1) Get task-specific memory before you start\ncm context \"implement auth rate limiting\" --json\n\n# 2) See the minimum viable workflow\ncm quickstart --json\n\n# 3) Build the playbook (memory onboarding)\ncm onboard status --json\ncm onboard sample --fill-gaps --json\ncm onboard read /path/to/session.jsonl --template --json\ncm onboard mark-done /path/to/session.jsonl\n```\n\n## Table of Contents\n\n- [Why This Exists](#-why-this-exists)\n- [How It Works](#-how-it-works)\n- [Key Features](#-key-features)\n- [For AI Agents](#-for-ai-agents-the-most-important-section)\n- [Installation](#-installation)\n- [CLI Reference](#-cli-reference)\n- [The ACE Pipeline](#-the-ace-pipeline)\n- [Data Models](#-data-models)\n- [Scoring Algorithm](#-scoring-algorithm)\n- [Configuration](#-configuration)\n- [MCP Server](#-mcp-server)\n- [Architecture \u0026 Engineering](#-architecture--engineering)\n- [Deep Dive: Core Algorithms](#-deep-dive-core-algorithms)\n- [Privacy \u0026 Security](#-privacy--security)\n- [Trauma Guard: Safety System](#-trauma-guard-safety-system)\n- [Performance Characteristics](#-performance-characteristics)\n- [Starter Playbooks](#-starter-playbooks)\n- [Extensibility](#-extensibility-adding-new-components)\n- [Troubleshooting](#-troubleshooting)\n- [Design Philosophy](#-design-philosophy)\n- [Comparison with Alternatives](#-comparison-with-alternatives)\n- [Roadmap](#-roadmap)\n\n---\n\n## 💡 Why This Exists\n\n### The Problem\n\nAI coding agents accumulate valuable knowledge through sessions: debugging strategies, code patterns, user preferences, project-specific insights. But this knowledge is:\n\n1. **Trapped in sessions** — Each session ends, context is lost forever\n2. **Agent-specific** — Claude Code doesn't know what Cursor learned yesterday\n3. **Unstructured** — Raw conversation logs aren't actionable as guidance\n4. **Subject to collapse** — Naive summarization loses critical nuances and details\n\nYou've solved authentication bugs three times this month across different agents. Each time, you started from scratch because the knowledge from previous sessions was inaccessible.\n\n### The Solution\n\n`cass-memory` implements a **three-layer cognitive architecture** that transforms raw session logs into actionable, confidence-tracked rules:\n\n| Layer | Role | Implementation |\n|-------|------|----------------|\n| **Episodic Memory** | Raw ground truth from all agents | `cass` search engine |\n| **Working Memory** | Structured session summaries | Diary entries |\n| **Procedural Memory** | Distilled rules with tracking | Playbook bullets |\n\nThis mirrors how human expertise develops: raw experiences (episodic) are consolidated into structured memories (working), which eventually become automatic knowledge (procedural).\n\n### Who Benefits\n\n- **AI Agents**: Get relevant rules and historical context before starting any task\n- **Developers**: Build institutional memory that persists across tools and sessions\n- **Teams**: Share patterns discovered by any team member's AI assistant\n- **Power Users**: Create sophisticated workflows that leverage cross-agent learning\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    EPISODIC MEMORY (cass)                           │\n│   Raw session logs from all agents — the \"ground truth\"             │\n│   Claude Code │ Codex │ Cursor │ Aider │ PI │ Gemini │ ChatGPT │ ... │\n└───────────────────────────┬─────────────────────────────────────────┘\n                            │ cass search\n                            ▼\n┌─────────────────────────────────────────────────────────────────────┐\n│                    WORKING MEMORY (Diary)                           │\n│   Structured session summaries bridging raw logs to rules           │\n│   accomplishments │ decisions │ challenges │ outcomes               │\n└───────────────────────────┬─────────────────────────────────────────┘\n                            │ reflect + curate (automated)\n                            ▼\n┌─────────────────────────────────────────────────────────────────────┐\n│                    PROCEDURAL MEMORY (Playbook)                     │\n│   Distilled rules with confidence tracking                          │\n│   Rules │ Anti-patterns │ Feedback │ Decay                          │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\nEvery agent's sessions feed the shared memory. A pattern discovered in Cursor **automatically** helps Claude Code on the next session.\n\n---\n\n## ✨ Key Features\n\n### Cross-Agent Learning\n\nSessions from all your AI coding agents feed a unified knowledge base:\n\n```\nClaude Code session    →  ┐\nCursor session         →  │→  Unified Playbook  →  All agents benefit\nCodex session          →  │\nAider session          →  │\nPI session             →  ┘\n```\n\nA debugging technique discovered in Cursor is immediately available to Claude Code. No manual knowledge transfer required.\n\n### Confidence Decay System\n\nRules aren't immortal. A rule helpful 8 times in January but never validated since loses confidence over time:\n\n- **90-day half-life**: Confidence halves every 90 days without revalidation\n- **4x harmful multiplier**: One mistake counts 4× as much as one success\n- **Maturity progression**: `candidate` → `established` → `proven`\n\nThis prevents stale rules from polluting your playbook while rewarding consistently helpful guidance.\n\n### Anti-Pattern Learning\n\nBad rules don't just get deleted—they become **warnings**:\n\n```\n\"Cache auth tokens for performance\"\n    ↓ (3 harmful marks)\n\"PITFALL: Don't cache auth tokens without expiry validation\"\n```\n\nWhen a rule is marked harmful multiple times, it's automatically inverted into an anti-pattern that warns future agents away from the same mistake.\n\n### Scientific Validation\n\nNew rules aren't blindly accepted. Before a rule joins your playbook, it's validated against your cass history:\n\n```\nProposed rule: \"Always check token expiry before auth debugging\"\n    ↓\nEvidence gate: Search cass for sessions where this applied\n    ↓\nResult: 5 sessions found, 4 successful outcomes → ACCEPT\n```\n\nRules without historical evidence are flagged as candidates until proven.\n\n### Graceful Degradation\n\nThe system works even when components are missing:\n\n| Condition | Behavior |\n|-----------|----------|\n| No cass | Playbook-only scoring, no history snippets |\n| No playbook | Empty playbook, commands still work |\n| No LLM | Deterministic reflection, no semantic enhancement |\n| Offline | Cached playbook + local diary |\n\nYou always get value, even in degraded conditions.\n\n---\n\n## 🤖 For AI Agents: The Most Important Section\n\n`cass-memory` is designed **specifically** for AI coding agents—not just as an afterthought, but as a first-class design goal. When you're an AI agent working on a codebase, cross-agent memory becomes invaluable: rules learned by other agents, context about design decisions, debugging approaches that worked, and institutional memory that would otherwise be lost.\n\n### Why Cross-Agent Memory Matters\n\nImagine you're Claude Code working on a React authentication bug. With `cass-memory`, you can instantly access:\n- Rules extracted from previous Claude sessions about auth patterns\n- Debugging strategies discovered by Cursor last week\n- Anti-patterns identified when Codex hit the same issue\n- Historical context from Aider about the codebase's auth architecture\n\nThis cross-pollination of knowledge across different AI agents is transformative. Each agent has different strengths, different context windows, and encounters different problems. `cass-memory` unifies all this collective intelligence into a single, searchable, actionable knowledge base.\n\n### The One Command You Need\n\n```bash\ncm context \"\u003cyour task\u003e\" --json\n```\n\n**Run this command before starting any non-trivial task.** It returns:\n- **Relevant rules** from the playbook (scored by task relevance)\n- **Historical context** from past sessions (yours and other agents')\n- **Anti-patterns** to avoid (things that have caused problems)\n- **Suggested searches** for deeper investigation\n\n### Self-Documenting API\n\n`cass-memory` teaches agents how to use it—no external documentation required:\n\n```bash\n# Quick capability check and self-explanation\ncm quickstart --json\n# → Returns complete explanation of the system and how to use it\n\n# System health and available features\ncm doctor --json\n# → { checks: [...], recommendations: [...], ... }\n\n# Get relevant context for a task\ncm context \"implement user authentication\" --json\n# → { relevantBullets: [...], antiPatterns: [...], historySnippets: [...] }\n```\n\n### Structured Output Format\n\nEvery command supports `--json` for machine-readable output:\n\n```bash\ncm context \"fix the auth timeout bug\" --json\n```\n\n```json\n{\n  \"success\": true,\n  \"task\": \"fix the auth timeout bug\",\n  \"relevantBullets\": [\n    {\n      \"id\": \"b-8f3a2c\",\n      \"content\": \"Always check token expiry before other auth debugging\",\n      \"effectiveScore\": 8.5,\n      \"maturity\": \"proven\",\n      \"relevanceScore\": 0.92,\n      \"reasoning\": \"Extracted from 5 successful sessions\"\n    }\n  ],\n  \"antiPatterns\": [\n    {\n      \"id\": \"b-x7k9p1\",\n      \"content\": \"Don't cache auth tokens without expiry validation\",\n      \"effectiveScore\": 3.2\n    }\n  ],\n  \"historySnippets\": [\n    {\n      \"source_path\": \"~/.claude/sessions/session-001.jsonl\",\n      \"agent\": \"claude\",\n      \"origin\": { \"kind\": \"local\" },\n      \"snippet\": \"Fixed timeout by increasing token refresh interval...\",\n      \"score\": 0.87\n    }\n  ],\n  \"suggestedCassQueries\": [\n    \"cass search 'authentication timeout' --robot --days 30\"\n  ],\n  \"degraded\": null\n}\n```\n\n**Design principle**: stdout contains only parseable JSON data; all diagnostics go to stderr.\n\n**Filtering remote vs local history:** `historySnippets[].origin.kind` is `\"local\"` or `\"remote\"`; remote hits include `origin.host`.\n\n### Error Handling for Agents\n\nErrors are structured and include recovery hints:\n\n```json\n{\n  \"success\": false,\n  \"code\": \"PLAYBOOK_NOT_FOUND\",\n  \"error\": \"Playbook file not found at ~/.cass-memory/playbook.yaml\",\n  \"hint\": \"Run 'cm init' to create a new playbook\",\n  \"retryable\": false\n}\n```\n\n### Token Budget Management\n\nAI agents have context limits. `cass-memory` provides controls to manage output size:\n\n| Flag | Effect |\n|------|--------|\n| `--limit N` | Cap number of rules returned |\n| `--min-score N` | Only return rules above score threshold |\n| `--no-history` | Skip historical snippets (faster, smaller) |\n| `--json` | Structured output for parsing |\n\n### Inline Feedback (During Work)\n\nWhen a rule helps or hurts during your work, leave inline feedback:\n\n```typescript\n// [cass: helpful b-8f3a2c] - this rule saved me from a rabbit hole\n\n// [cass: harmful b-x7k9p1] - this advice was wrong for our use case\n```\n\nThese comments are automatically parsed during reflection and update rule confidence.\n\n### Session Outcome Recording\n\nAfter completing a task, record the outcome:\n\n```bash\n# Record successful outcome (positional: status, rules)\ncm outcome success b-8f3a2c,b-xyz789 --summary \"Fixed auth bug\"\n\n# Record failure\ncm outcome failure b-x7k9p1 --summary \"Rule led to wrong approach\"\n\n# Apply recorded outcomes to playbook\ncm outcome-apply\n```\n\n### What NOT to Do\n\nYou do NOT need to:\n- Run `cm reflect` (automation handles this)\n- Run `cm mark` manually (use inline comments instead)\n- Manually add rules to the playbook\n- Worry about the learning pipeline\n\nThe system learns from your sessions automatically. Your job is just to **query context before working**.\n\n### Ready-to-Paste Blurb for AGENTS.md / CLAUDE.md\n\n```markdown\n## Memory System: cass-memory\n\nThe Cass Memory System (cm) is a tool for giving agents an effective memory based on the ability to quickly search across previous coding agent sessions across an array of different coding agent tools (e.g., Claude Code, Codex, Gemini-CLI, Cursor, etc) and projects (and even across multiple machines, optionally) and then reflect on what they find and learn in new sessions to draw out useful lessons and takeaways; these lessons are then stored and can be queried and retrieved later, much like how human memory works.\n\nThe `cm onboard` command guides you through analyzing historical sessions and extracting valuable rules.\n\n### Quick Start\n\n```bash\n# 1. Check status and see recommendations\ncm onboard status\n\n# 2. Get sessions to analyze (filtered by gaps in your playbook)\ncm onboard sample --fill-gaps\n\n# 3. Read a session with rich context\ncm onboard read /path/to/session.jsonl --template\n\n# 4. Add extracted rules (one at a time or batch)\ncm playbook add \"Your rule content\" --category \"debugging\"\n# Or batch add:\ncm playbook add --file rules.json\n\n# 5. Mark session as processed\ncm onboard mark-done /path/to/session.jsonl\n```\n\nBefore starting complex tasks, retrieve relevant context:\n\n```bash\ncm context \"\u003ctask description\u003e\" --json\n```\n\nThis returns:\n- **relevantBullets**: Rules that may help with your task\n- **antiPatterns**: Pitfalls to avoid\n- **historySnippets**: Past sessions that solved similar problems\n- **suggestedCassQueries**: Searches for deeper investigation\n\n### Protocol\n\n1. **START**: Run `cm context \"\u003ctask\u003e\" --json` before non-trivial work\n2. **WORK**: Reference rule IDs when following them (e.g., \"Following b-8f3a2c...\")\n3. **FEEDBACK**: Leave inline comments when rules help/hurt:\n   - `// [cass: helpful b-xyz] - reason`\n   - `// [cass: harmful b-xyz] - reason`\n4. **END**: Just finish your work. Learning happens automatically.\n\n### Key Flags\n\n| Flag | Purpose |\n|------|---------|\n| `--json` | Machine-readable JSON output (required!) |\n| `--limit N` | Cap number of rules returned |\n| `--no-history` | Skip historical snippets for faster response |\n\nstdout = data only, stderr = diagnostics. Exit 0 = success.\n```\n\n---\n\n## 🎓 Agent-Native Onboarding\n\nBuilding a playbook from scratch can be daunting—but you don't need to spend money on LLM API calls to do it. The **agent-native onboarding** system leverages the AI coding agent you're already paying for (via Claude Max, ChatGPT Pro, Cursor Pro, etc.) to analyze historical sessions and extract rules.\n\n### The Zero-Cost Approach\n\nTraditional approaches to building a playbook might suggest using external LLM APIs to analyze sessions and extract rules. But if you're already running an AI coding agent, **that agent can do the analysis work itself**—at no additional cost.\n\n```\nTraditional approach:\n  Sessions → External LLM API → Rules → $ cost per session\n\nAgent-native approach:\n  Sessions → Your Agent (already paid for) → Rules → $0 additional cost\n```\n\nThe `cm onboard` command guides your agent through analyzing historical sessions and extracting valuable rules.\n\n### Quick Start\n\n```bash\n# 1. Check status and see recommendations\ncm onboard status\n\n# 2. Get sessions to analyze (filtered by gaps in your playbook)\ncm onboard sample --fill-gaps\n\n# 3. Read a session with rich context\ncm onboard read /path/to/session.jsonl --template\n\n# 4. Add extracted rules (one at a time or batch)\ncm playbook add \"Your rule content\" --category \"debugging\"\n# Or batch add:\ncm playbook add --file rules.json\n\n# 5. Mark session as processed\ncm onboard mark-done /path/to/session.jsonl\n```\n\n### Gap Analysis\n\nNot all playbook categories are equally represented. The gap analysis system identifies **underrepresented categories** so you can prioritize which sessions to analyze.\n\n**Categories tracked:**\n- `debugging` — Error resolution, bug fixing, tracing\n- `testing` — Unit tests, mocks, assertions, coverage\n- `architecture` — Design patterns, module structure, abstractions\n- `workflow` — Task management, CI/CD, deployment\n- `documentation` — Comments, READMEs, API docs\n- `integration` — APIs, HTTP, JSON parsing, endpoints\n- `collaboration` — Code review, PRs, team coordination\n- `git` — Version control, branching, merging\n- `security` — Auth, encryption, vulnerability prevention\n- `performance` — Optimization, caching, profiling\n\n**Category status thresholds:**\n| Status | Rule Count | Priority |\n|--------|------------|----------|\n| `critical` | 0 rules | High |\n| `underrepresented` | 1-2 rules | Medium |\n| `adequate` | 3-10 rules | Low |\n| `well-covered` | 11+ rules | None |\n\n```bash\n# View detailed gap analysis\ncm onboard gaps\n\n# Sample sessions prioritized for gap-filling\ncm onboard sample --fill-gaps\n```\n\n### Progress Tracking\n\nOnboarding progress persists across sessions, so agents can resume where they left off even after context window limits are reached.\n\n**State stored at:** `~/.cass-memory/onboarding-state.json`\n\n```json\n{\n  \"version\": 1,\n  \"startedAt\": \"2025-01-15T10:30:00Z\",\n  \"lastUpdatedAt\": \"2025-01-15T14:45:00Z\",\n  \"processedSessions\": [\n    {\n      \"path\": \"/Users/x/.claude/sessions/session-001.jsonl\",\n      \"processedAt\": \"2025-01-15T11:00:00Z\",\n      \"rulesExtracted\": 3\n    }\n  ],\n  \"stats\": {\n    \"totalSessionsProcessed\": 5,\n    \"totalRulesExtracted\": 12\n  }\n}\n```\n\nCommands for progress management:\n```bash\n# Check progress\ncm onboard status\n\n# Mark a session as done (even if no rules extracted)\ncm onboard mark-done /path/to/session.jsonl\n\n# Reset progress to start fresh\ncm onboard reset\n```\n\n### Batch Rule Addition\n\nAfter analyzing a session, add multiple rules at once using the batch add feature:\n\n```bash\n# Create a JSON file with rules\ncat \u003e rules.json \u003c\u003c 'EOF'\n[\n  {\"content\": \"Always run tests before committing\", \"category\": \"testing\"},\n  {\"content\": \"Check token expiry before auth debugging\", \"category\": \"debugging\"},\n  {\"content\": \"AVOID: Mocking entire modules in tests\", \"category\": \"testing\"}\n]\nEOF\n\n# Add all rules at once\ncm playbook add --file rules.json\n\n# Or pipe from another command\necho '[{\"content\": \"Rule from stdin\", \"category\": \"workflow\"}]' | cm playbook add --file -\n\n# Track which session the rules came from\ncm playbook add --file rules.json --session /path/to/session.jsonl\n```\n\nThe `--session` flag automatically updates onboarding progress, crediting the session with the number of rules extracted.\n\n### Template Output for Rich Context\n\nThe `--template` flag provides agents with rich contextual information to guide extraction:\n\n```bash\ncm onboard read /path/to/session.jsonl --template --json\n```\n\n**Template output includes:**\n\n```json\n{\n  \"metadata\": {\n    \"path\": \"/path/to/session.jsonl\",\n    \"workspace\": \"/Users/x/project\",\n    \"messageCount\": 127,\n    \"topicHints\": [\"debugging\", \"testing\", \"git\"]\n  },\n  \"context\": {\n    \"relatedRules\": [\n      {\"id\": \"b-abc123\", \"content\": \"...\", \"similarity\": 0.72}\n    ],\n    \"playbookGaps\": {\n      \"critical\": [\"security\", \"performance\"],\n      \"underrepresented\": [\"collaboration\"]\n    },\n    \"suggestedFocus\": \"This session may contain security patterns - you have NO rules in this area!\"\n  },\n  \"extractionFormat\": {\n    \"schema\": {\"content\": \"string\", \"category\": \"string\"},\n    \"categories\": [\"debugging\", \"testing\", \"architecture\", ...],\n    \"examples\": [...]\n  },\n  \"sessionContent\": \"...\"\n}\n```\n\n**Template features:**\n- **Topic hints**: Categories detected from session content using keyword matching\n- **Related rules**: Existing playbook rules similar to the session content (via semantic search if enabled)\n- **Playbook gaps**: Categories with missing or few rules\n- **Suggested focus**: AI-generated guidance on what to prioritize based on gaps and detected topics\n- **Examples**: Sample rules showing proper format for each category\n\n### Gap-Targeted Sampling Algorithm\n\nWhen using `--fill-gaps`, the sampling algorithm prioritizes sessions likely to contain patterns for underrepresented categories:\n\n```\n1. Analyze playbook → Identify critical/underrepresented categories\n2. Generate search queries from category keywords:\n   - \"security\" → \"security auth token\"\n   - \"performance\" → \"performance optimize cache\"\n3. Search cass with gap-targeted queries\n4. Score each session against gaps:\n   - Session matches critical category: +3 points\n   - Session matches underrepresented category: +2 points\n   - Session matches adequate category: +1 point\n5. Sort sessions by gap score (highest first)\n6. Filter out already-processed sessions\n7. Return top N sessions\n```\n\n**Category keyword detection** uses a lightweight approach (no external APIs required):\n\n```typescript\n// Example: detecting categories from text\nconst CATEGORY_KEYWORDS = {\n  debugging: [\"debug\", \"error\", \"fix\", \"bug\", \"trace\", \"stack\", ...],\n  testing: [\"test\", \"mock\", \"assert\", \"expect\", \"jest\", \"vitest\", ...],\n  security: [\"security\", \"auth\", \"token\", \"encrypt\", \"permission\", ...],\n  // ... more categories\n};\n\n// Count keyword matches → category with most matches wins\n```\n\n### Targeted Sampling Options\n\nFilter sessions by various criteria to focus on specific areas:\n\n```bash\n# Filter by workspace/project\ncm onboard sample --workspace /Users/x/my-project\n\n# Filter by agent\ncm onboard sample --agent claude\ncm onboard sample --agent cursor\n\n# Filter by recency\ncm onboard sample --days 30\n\n# Combine filters\ncm onboard sample --agent claude --days 14 --workspace /Users/x/api-project\n\n# Include already-processed sessions (for re-analysis)\ncm onboard sample --include-processed\n\n# Adjust sample size\ncm onboard sample --limit 20\n```\n\n### Onboarding Workflow for Agents\n\nRecommended protocol for AI agents doing onboarding:\n\n```markdown\n## Onboarding Protocol\n\n### Phase 1: Assessment\n1. Run `cm onboard status --json` to check current progress\n2. Run `cm onboard gaps --json` to see category distribution\n3. Decide target: ~20 rules across diverse categories for a good initial playbook\n\n### Phase 2: Session Analysis Loop\nFor each session until target reached:\n1. `cm onboard sample --fill-gaps --json` → get prioritized sessions\n2. `cm onboard read \u003cpath\u003e --template --json` → get session with context\n3. Analyze session content, identify 2-5 reusable patterns\n4. Format as rules following extraction guidelines\n5. `cm playbook add --file rules.json --session \u003cpath\u003e` → add rules\n6. Repeat with next session\n\n### Phase 3: Verification\n1. `cm onboard status` → verify progress\n2. `cm onboard gaps` → check remaining gaps\n3. `cm stats --json` → verify playbook health\n```\n\n### Why Agent-Native Onboarding?\n\n1. **Zero additional cost**: Uses the AI agent you're already paying for\n2. **Better analysis**: Your agent understands your codebase context\n3. **Resumable**: Progress persists across sessions\n4. **Gap-aware**: Automatically prioritizes underrepresented categories\n5. **Batch-friendly**: Add multiple rules efficiently\n6. **Self-documenting**: Template output guides extraction\n\n---\n\n## 📦 Installation\n\n### One-Liner (Recommended)\n\n#### Recommended: Homebrew (macOS/Linux)\n\n```bash\nbrew install dicklesworthstone/tap/cm\n```\n\nThis method provides:\n- Automatic updates via `brew upgrade`\n- Dependency management\n- Easy uninstall via `brew uninstall`\n\n#### Windows: Scoop\n\n```powershell\nscoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket\nscoop install dicklesworthstone/cm\n```\n\n#### Alternative: Install Script\n\n**Linux/macOS:**\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh?$(date +%s)\" \\\n  | bash -s -- --easy-mode --verify\n```\n\n**Direct Downloads:**\n- [Linux x64](https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-linux-x64)\n- [macOS Apple Silicon](https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-macos-arm64)\n- [macOS Intel](https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-macos-x64)\n- [Windows x64](https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-windows-x64.exe)\n\n### Installer Options\n\n```bash\n# Full options\ninstall.sh [--version vX.Y.Z] [--dest DIR] [--system] [--easy-mode] [--verify]\n           [--from-source] [--quiet]\n\n# Examples\ninstall.sh --version v0.2.2 --verify    # Specific version\ninstall.sh --system --verify             # Install to /usr/local/bin (requires sudo)\ninstall.sh --from-source                 # Build from source (requires bun)\n```\n\n| Flag | Effect |\n|------|--------|\n| `--version` | Install specific version (default: latest) |\n| `--dest DIR` | Install to custom directory (default: ~/.local/bin) |\n| `--system` | Install to /usr/local/bin (requires sudo) |\n| `--easy-mode` | Non-interactive, auto-configure PATH |\n| `--verify` | Run self-test after install |\n| `--from-source` | Build from source instead of downloading binary |\n| `--quiet` | Suppress output |\n\n### Installer Robustness\n\nThe installer is designed for reliability:\n\n- **No API rate limits**: Uses GitHub redirect detection instead of API calls, avoiding the 60 requests/hour unauthenticated limit\n- **Checksum verification**: Downloads `.sha256` files and verifies binary integrity before installation\n- **Concurrent install protection**: Lock file prevents multiple installers from running simultaneously\n- **Graceful fallbacks**: If binary download fails, automatically falls back to building from source\n- **Cross-platform checksums**: Uses `sha256sum` on Linux, `shasum -a 256` on macOS\n\n### From Source\n\n```bash\ngit clone https://github.com/Dicklesworthstone/cass_memory_system.git\ncd cass_memory_system\nbun install\nbun run build\nsudo mv ./dist/cass-memory /usr/local/bin/cm\n```\n\n### Prerequisites\n\n- **cass CLI**: The episodic memory layer. Install from [cass repo](https://github.com/Dicklesworthstone/coding_agent_session_search)\n- **LLM API Key** (optional): For AI-powered reflection. Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`\n\n### Verify Installation\n\n```bash\ncm --version\ncm doctor --json\n```\n\n### Initial Setup\n\n```bash\n# Initialize (creates global config and playbook)\ncm init\n\n# Or with a starter playbook for common patterns\ncm init --starter typescript  # or: react, python, go\ncm starters  # list available starters\n```\n\n### Automating Reflection\n\nThe key to the system is automated reflection. Set up a cron job or hook:\n\n```bash\n# Daily reflection on recent sessions\ncm reflect --days 7 --json\n\n# Via cron (runs at 2am daily)\n0 2 * * * /usr/local/bin/cm reflect --days 7 \u003e\u003e ~/.cass-memory/reflect.log 2\u003e\u00261\n```\n\nFor Claude Code users, add a post-session hook in `.claude/hooks.json`:\n```json\n{\n  \"post-session\": [\"cm reflect --days 1\"]\n}\n```\n\n---\n\n## 🛠️ CLI Reference\n\n### Quick Reference Table\n\n| Command | Purpose | Agent Use |\n|---------|---------|-----------|\n| `cm context \"\u003ctask\u003e\" --json` | Get rules + history for task | **Primary** |\n| `cm quickstart --json` | Self-documentation | Setup |\n| `cm doctor --json` | System health check | Diagnostics |\n| `cm playbook list` | Show all rules | Inspection |\n| `cm similar \"\u003cquery\u003e\"` | Find similar rules | Search |\n| `cm stats --json` | Playbook metrics | Analytics |\n| `cm trauma list` | Show dangerous patterns | Safety |\n| `cm guard --status` | Check safety hook status | Safety |\n\n### Error Output \u0026 Exit Codes\n\nWhen `--json` (or `--format json`) is enabled, errors are printed to stdout as a single JSON object:\n\n```json\n{\n  \"success\": false,\n  \"error\": \"…\",\n  \"code\": \"…\",\n  \"exitCode\": 2,\n  \"recovery\": [\"…\", \"…\"],\n  \"cause\": \"…\",\n  \"docs\": \"README.md#-troubleshooting\",\n  \"hint\": \"…\",\n  \"details\": {}\n}\n```\n\nExit codes are categorized for scripting:\n\n- `1` internal (bug / unexpected)\n- `2` user input / usage\n- `3` configuration\n- `4` filesystem\n- `5` network\n- `6` cass\n- `7` LLM/provider\n\n### Agent Commands (Primary Workflow)\n\n```bash\n# Get context before starting a task (THE MAIN COMMAND)\ncm context \"implement user authentication\" --json\n\n# Self-documenting explanation of the system\ncm quickstart --json\n\n# Find rules similar to a query\ncm similar \"error handling best practices\"\n```\n\n### Playbook Commands (Inspect \u0026 Manage Rules)\n\n```bash\n# List all active rules\ncm playbook list\n\n# Get detailed info for a specific rule\ncm playbook get b-8f3a2c\n\n# Add a new rule manually\ncm playbook add \"Always run tests before committing\"\n\n# Remove/deprecate a rule\ncm playbook remove b-xyz789 --reason \"No longer applicable\"\n\n# Export playbook for backup or sharing\ncm playbook export \u003e playbook-backup.yaml\n\n# Import playbook from file\ncm playbook import shared-playbook.yaml\n\n# Show top N most effective rules\ncm top 10\n\n# Find rules without recent feedback (stale)\ncm stale --days 60\n\n# Show why a rule exists (provenance)\ncm why b-8f3a2c\n\n# Get playbook health metrics\ncm stats --json\n```\n\n### Learning Commands (Feedback \u0026 Reflection)\n\n```bash\n# Process recent sessions into rules (usually automated)\ncm reflect --days 7 --json\n\n# Manual feedback on a rule\ncm mark b-8f3a2c --helpful\ncm mark b-xyz789 --harmful --reason \"Caused regression\"\n\n# Record session outcome (positional: status, rules)\ncm outcome success b-8f3a2c,b-def456\ncm outcome failure b-x7k9p1 --summary \"Auth approach failed\"\n\n# Apply recorded outcomes to playbook\ncm outcome-apply\n\n# Validate a proposed rule against history\ncm validate \"Always check null before dereferencing\"\n\n# Deprecate a rule permanently\ncm forget b-xyz789 --reason \"Superseded by better pattern\"\n\n# Revert a curation decision\ncm undo b-xyz789\n\n# Check sessions for rule violations\ncm audit --days 30\n```\n\n### System Commands (Setup \u0026 Diagnostics)\n\n```bash\n# Initialize configuration and playbook\ncm init\ncm init --starter typescript  # With starter template\ncm starters                   # List available starters\n\n# Check system health\ncm doctor --json\ncm doctor --fix               # Auto-fix issues\n\n# Export rules for AGENTS.md\ncm project --format agents.md\n\n# Show LLM cost and usage statistics\ncm usage\n\n# Run MCP HTTP server for agent integration (default: 127.0.0.1:8765)\ncm serve\n\n# Privacy controls\ncm privacy status\ncm privacy enable   # Enable cross-agent enrichment\ncm privacy disable  # Disable cross-agent enrichment\n```\n\n### Safety Commands (Trauma Guard)\n\n```bash\n# View active trauma patterns\ncm trauma list\n\n# Add a dangerous pattern\ncm trauma add \"DROP TABLE\" --description \"Database table deletion\" --severity critical\n\n# Temporarily disable a pattern\ncm trauma heal t-abc123 --reason \"Intentional migration cleanup\"\n\n# Permanently remove a pattern\ncm trauma remove t-abc123\n\n# Scan sessions for potential traumas\ncm trauma scan --days 30\n\n# Import patterns from file\ncm trauma import shared-traumas.yaml\n\n# Install safety hooks\ncm guard --install           # Claude Code pre-tool hook\ncm guard --git               # Git pre-commit hook\ncm guard --install --git     # Both\ncm guard --status            # Check installation status\n```\n\n### Command Output Modes\n\nAll commands support multiple output formats:\n\n| Flag | Output |\n|------|--------|\n| (default) | Human-readable text |\n| `--json` | Machine-readable JSON |\n| `--quiet` | Minimal output |\n\n---\n\n## 🔬 The ACE Pipeline\n\n`cass-memory` implements the **Agentic Context Engineering (ACE)** framework with four stages:\n\n```\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  GENERATOR   │ ──▶ │  REFLECTOR   │ ──▶ │  VALIDATOR   │ ──▶ │   CURATOR    │\n│              │     │              │     │              │     │              │\n│ Pre-task     │     │ LLM pattern  │     │ Evidence     │     │ Deterministic│\n│ context      │     │ extraction   │     │ gate against │     │ delta merge  │\n│ hydration    │     │ from diary   │     │ cass history │     │ (NO LLM!)    │\n└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘\n```\n\n### Stage 1: Generator (`cm context`)\n\nHydrates the agent with relevant rules before starting a task.\n\n**Implementation** (`src/commands/context.ts`):\n\n```typescript\nasync function generateContext(task: string): Promise\u003cContextResult\u003e {\n  // 1. Extract keywords from task\n  const keywords = extractKeywords(task);\n\n  // 2. Score all playbook bullets against keywords\n  const scoredBullets = playbook.bullets\n    .map(bullet =\u003e ({\n      ...bullet,\n      relevanceScore: scoreRelevance(bullet, keywords),\n      effectiveScore: getEffectiveScore(bullet)\n    }))\n    .filter(b =\u003e b.relevanceScore \u003e config.minRelevanceScore)\n    .sort((a, b) =\u003e b.relevanceScore * b.effectiveScore - a.relevanceScore * a.effectiveScore);\n\n  // 3. Search cass for historical context\n  const historySnippets = await safeCassSearch(task, {\n    limit: config.maxHistoryInContext,\n    days: config.sessionLookbackDays\n  });\n\n  // 4. Return ranked results\n  return {\n    task,\n    relevantBullets: scoredBullets.slice(0, config.maxBulletsInContext),\n    antiPatterns: scoredBullets.filter(b =\u003e b.type === 'anti-pattern'),\n    historySnippets,\n    suggestedCassQueries: generateSuggestedQueries(task, keywords)\n  };\n}\n```\n\n### Stage 2: Reflector (`cm reflect`)\n\nProcesses unprocessed sessions to extract new rules.\n\n**How It Works**:\n\n1. **Find unprocessed sessions** via cass timeline API\n2. **Generate diary entries** - structured summaries of each session:\n   - Accomplishments (what was completed)\n   - Decisions (design choices made)\n   - Challenges (problems encountered)\n   - Key learnings (reusable insights)\n3. **Run LLM reflector** - multi-iteration pattern extraction\n4. **Output deltas** - add/helpful/harmful/deprecate operations\n\n**The Reflector Prompt** (simplified):\n\n```\nAnalyze this session diary and extract actionable rules.\nFor each pattern you identify:\n1. Formulate as an imperative rule (\"Always...\", \"Never...\", \"When X, do Y\")\n2. Categorize (testing, debugging, git, architecture, etc.)\n3. Assess scope (global, workspace, language, framework)\n4. Provide reasoning for why this is valuable\n\nOutput format: JSON array of proposed rules\n```\n\n### Stage 3: Validator\n\nScientific gate ensuring rules have evidence.\n\n**Implementation** (`src/ace/validator.ts`):\n\n```typescript\nasync function validateRule(rule: ProposedRule): Promise\u003cValidationResult\u003e {\n  // 1. Evidence count gate - fast pre-filter\n  const evidenceCount = await countEvidenceInCass(rule);\n  if (evidenceCount \u003c MIN_EVIDENCE_COUNT) {\n    return { verdict: 'NEEDS_MORE_EVIDENCE', evidenceCount };\n  }\n\n  // 2. LLM validation - deep analysis\n  const llmVerdict = await llmValidate(rule, evidenceCount);\n\n  // 3. Final verdict\n  return {\n    verdict: llmVerdict.valid ? 'ACCEPT' : 'REJECT',\n    reasoning: llmVerdict.reasoning,\n    evidenceCount\n  };\n}\n```\n\n### Stage 4: Curator\n\n**Critical: NO LLM in this stage** - pure deterministic logic to prevent context collapse.\n\n**Why No LLM?** LLMs tend to \"drift\" when iteratively refining their own outputs. By keeping curation deterministic, we:\n- Prevent feedback loops that degrade rule quality\n- Ensure reproducible behavior\n- Avoid expensive redundant LLM calls\n\n**Curation Operations**:\n\n```typescript\nfunction curate(playbook: Playbook, deltas: Delta[]): Playbook {\n  for (const delta of deltas) {\n    switch (delta.type) {\n      case 'add':\n        // Conflict detection - find contradicting rules\n        const conflicts = findConflicts(playbook, delta.rule);\n        if (conflicts.length \u003e 0) {\n          resolveConflicts(playbook, conflicts, delta);\n        }\n\n        // Duplicate detection - hash-based and semantic\n        const duplicate = findDuplicate(playbook, delta.rule);\n        if (duplicate) {\n          mergeDuplicate(duplicate, delta.rule);\n          continue;\n        }\n\n        // Add new rule\n        playbook.bullets.push(delta.rule);\n        break;\n\n      case 'helpful':\n        // Update feedback\n        addFeedback(playbook, delta.bulletId, 'helpful', delta.timestamp);\n        maybePromoteMaturity(playbook, delta.bulletId);\n        break;\n\n      case 'harmful':\n        // Update feedback with harmful multiplier consideration\n        addFeedback(playbook, delta.bulletId, 'harmful', delta.timestamp);\n        maybeConvertToAntiPattern(playbook, delta.bulletId);\n        break;\n\n      case 'deprecate':\n        deprecateRule(playbook, delta.bulletId, delta.reason);\n        break;\n    }\n  }\n\n  // Maturity promotions based on feedback thresholds\n  promoteQualifiedRules(playbook);\n\n  return playbook;\n}\n```\n\n---\n\n## 📊 Data Models\n\n### Playbook Bullet\n\nThe core data structure for rules:\n\n```typescript\ninterface PlaybookBullet {\n  // Identity\n  id: string;                    // \"b-{timestamp}-{random}\"\n  content: string;               // The actual rule\n  category: string;              // \"testing\" | \"git\" | \"debugging\" | etc.\n\n  // Classification\n  scope: \"global\" | \"workspace\" | \"language\" | \"framework\" | \"task\";\n  type: \"rule\" | \"anti-pattern\";\n  kind: \"project_convention\" | \"stack_pattern\" | \"workflow_rule\" | \"anti_pattern\";\n  isNegative: boolean;\n\n  // Lifecycle\n  state: \"draft\" | \"active\" | \"retired\";\n  maturity: \"candidate\" | \"established\" | \"proven\" | \"deprecated\";\n\n  // Feedback \u0026 Scoring\n  helpfulCount: number;          // Raw count\n  harmfulCount: number;          // Raw count\n  feedbackEvents: FeedbackEvent[];  // Full history with timestamps\n  effectiveScore?: number;       // Calculated decay-adjusted score\n\n  // Provenance\n  sourceSessions: string[];      // Sessions that generated this rule\n  sourceAgents: string[];        // Agents involved (claude, codex, cursor, etc.)\n  reasoning?: string;            // Why this rule exists\n  sourceSession?: string;        // Flexible field for reflection metadata\n\n  // Metadata\n  tags: string[];\n  embedding?: number[];          // Semantic search vector (768 dimensions)\n  pinned: boolean;               // Prevent auto-deprecation\n  deprecated: boolean;\n\n  // Timestamps\n  createdAt: string;             // ISO 8601\n  updatedAt: string;             // ISO 8601\n}\n```\n\n### Feedback Event\n\nImmutable record of feedback:\n\n```typescript\ninterface FeedbackEvent {\n  id: string;                    // UUID\n  type: \"helpful\" | \"harmful\";\n  timestamp: string;             // ISO 8601\n  source: \"inline\" | \"manual\" | \"outcome\" | \"audit\";\n  sessionPath?: string;          // Session where feedback was given\n  reason?: string;               // Optional explanation\n}\n```\n\n### Diary Entry\n\nWorking memory structure:\n\n```typescript\ninterface DiaryEntry {\n  id: string;                    // Deterministic hash of content\n  sessionPath: string;           // Original cass session\n  timestamp: string;             // ISO 8601\n  agent: string;                 // \"claude\" | \"codex\" | \"cursor\" | etc.\n  workspace?: string;            // Project directory\n\n  // Session status\n  status: \"success\" | \"failure\" | \"mixed\";\n\n  // Core content\n  accomplishments: string[];     // What was completed\n  decisions: string[];           // Design choices made\n  challenges: string[];          // Problems encountered\n  keyLearnings: string[];        // Reusable insights\n  preferences: string[];         // User style revelations\n\n  // Cross-agent enrichment\n  relatedSessions?: RelatedSession[];\n\n  // Search optimization\n  searchAnchors: string[];       // Keywords for retrieval\n  tags: string[];                // File/component tags\n}\n```\n\n### Session Outcome\n\nExplicit outcome recording:\n\n```typescript\ninterface SessionOutcome {\n  id: string;                    // UUID\n  timestamp: string;             // ISO 8601\n  status: \"success\" | \"failure\" | \"mixed\";\n\n  // Associated rules\n  rulesUsed: string[];           // Bullet IDs that were followed\n  rulesViolated?: string[];      // Bullet IDs that were ignored\n\n  // Context\n  task?: string;                 // What was attempted\n  summary?: string;              // Brief description\n  sessionPath?: string;          // Source session\n\n  // Feedback impact\n  applied: boolean;              // Whether outcome-apply has processed this\n  appliedAt?: string;            // When it was applied\n}\n```\n\n---\n\n## 📈 Scoring Algorithm\n\n### Effective Score Calculation\n\nThe effective score determines rule ranking, maturity transitions, and anti-pattern conversion:\n\n```typescript\nfunction getEffectiveScore(bullet: PlaybookBullet): number {\n  const HARMFUL_MULTIPLIER = 4;    // One harmful = 4× one helpful\n  const HALF_LIFE_DAYS = 90;       // 90 days for half decay\n\n  // Calculate decayed helpful count\n  const decayedHelpful = bullet.feedbackEvents\n    .filter(e =\u003e e.type === \"helpful\")\n    .reduce((sum, event) =\u003e {\n      const daysAgo = daysSince(event.timestamp);\n      const decayFactor = Math.pow(0.5, daysAgo / HALF_LIFE_DAYS);\n      return sum + decayFactor;\n    }, 0);\n\n  // Calculate decayed harmful count\n  const decayedHarmful = bullet.feedbackEvents\n    .filter(e =\u003e e.type === \"harmful\")\n    .reduce((sum, event) =\u003e {\n      const daysAgo = daysSince(event.timestamp);\n      const decayFactor = Math.pow(0.5, daysAgo / HALF_LIFE_DAYS);\n      return sum + decayFactor;\n    }, 0);\n\n  // Effective score with harmful multiplier\n  return decayedHelpful - (HARMFUL_MULTIPLIER * decayedHarmful);\n}\n```\n\n### Score Decay Visualization\n\n```\nInitial score: 10.0 (10 helpful marks today)\n\nAfter 90 days (half-life):   5.0\nAfter 180 days:              2.5\nAfter 270 days:              1.25\nAfter 365 days:              0.78\n```\n\n### Why Time Decay?\n\n1. **Codebases evolve** - A pattern helpful for React 17 may not apply to React 19\n2. **Tools change** - Agent capabilities improve over time\n3. **Prevents stale rules** - Forces ongoing validation\n4. **Natural cleanup** - Unvalidated rules fade rather than accumulate\n\n### Maturity State Machine\n\n```\n  ┌──────────┐       ┌─────────────┐    ┌────────┐\n  │ candidate│──────▶│ established │───▶│ proven │\n  └──────────┘       └─────────────┘    └────────┘\n       │                   │                  │\n       │                   │ (harmful \u003e25%)   │\n       │                   ▼                  │\n       │             ┌─────────────┐          │\n       └────────────▶│ deprecated  │◀─────────┘\n                     └─────────────┘\n```\n\n**Transition Rules**:\n\n| Transition | Criteria |\n|------------|----------|\n| `candidate` → `established` | 3+ helpful, harmful ratio \u003c25% |\n| `established` → `proven` | 10+ helpful, harmful ratio \u003c10% |\n| `any` → `deprecated` | Harmful ratio \u003e25% OR explicit deprecation |\n\n### Anti-Pattern Conversion\n\nWhen a rule accumulates too much negative feedback:\n\n```typescript\nfunction maybeConvertToAntiPattern(playbook: Playbook, bulletId: string): void {\n  const bullet = playbook.getBullet(bulletId);\n  const harmfulRatio = bullet.harmfulCount / (bullet.helpfulCount + bullet.harmfulCount);\n\n  if (harmfulRatio \u003e 0.5 \u0026\u0026 bullet.harmfulCount \u003e= 3) {\n    // Convert to anti-pattern\n    const antiPattern: PlaybookBullet = {\n      ...bullet,\n      id: `b-anti-${Date.now()}`,\n      type: 'anti-pattern',\n      isNegative: true,\n      content: invertToAntiPattern(bullet.content),\n      // Reset feedback for new anti-pattern\n      helpfulCount: 0,\n      harmfulCount: 0,\n      feedbackEvents: [],\n      maturity: 'candidate',\n      reasoning: `Inverted from harmful rule ${bulletId}: ${bullet.reasoning}`\n    };\n\n    // Deprecate original\n    bullet.deprecated = true;\n    bullet.maturity = 'deprecated';\n\n    // Add anti-pattern\n    playbook.bullets.push(antiPattern);\n  }\n}\n\nfunction invertToAntiPattern(content: string): string {\n  // \"Always X\" → \"PITFALL: Don't always X\"\n  // \"Use X for Y\" → \"PITFALL: Avoid using X for Y without consideration\"\n  if (content.startsWith('Always ')) {\n    return `PITFALL: Don't ${content.slice(7).toLowerCase()}`;\n  }\n  if (content.startsWith('Use ')) {\n    return `PITFALL: Avoid ${content.slice(0, 1).toLowerCase() + content.slice(1)} without careful consideration`;\n  }\n  return `PITFALL: Avoid - ${content}`;\n}\n```\n\n---\n\n## ⚙️ Configuration\n\nConfig lives at `~/.cass-memory/config.json` (global) and `.cass/config.json` (repo).\n\n**Precedence:** CLI flags \u003e Repo config \u003e Global config \u003e Defaults\n\n**Security:** Repo config cannot override sensitive paths (`cassPath`, `playbookPath`, `diaryDir`) or user-level consent settings (`crossAgent`, `remoteCass`).\n\n### Complete Configuration Reference\n\n```json\n{\n  // LLM Settings\n  \"provider\": \"anthropic\",\n  \"model\": \"claude-sonnet-4-20250514\",\n  \"budget\": {\n    \"dailyLimit\": 0.10,\n    \"monthlyLimit\": 2.00,\n    \"warningThreshold\": 80\n  },\n\n  // Scoring Settings\n  \"scoring\": {\n    \"decayHalfLifeDays\": 90,\n    \"harmfulMultiplier\": 4,\n    \"minFeedbackForActive\": 3,\n    \"minHelpfulForProven\": 10,\n    \"maxHarmfulRatioForProven\": 0.1\n  },\n\n  // Context Settings\n  \"maxBulletsInContext\": 50,\n  \"maxHistoryInContext\": 10,\n  \"sessionLookbackDays\": 7,\n  \"minRelevanceScore\": 0.1,\n\n  // Privacy Settings\n  \"crossAgent\": {\n    \"enabled\": false,\n    \"consentGiven\": false,\n    \"agents\": [],\n    \"auditLog\": true\n  },\n\n  // Semantic Search Settings\n  \"semanticSearchEnabled\": false,\n  \"semanticWeight\": 0.6,\n  \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",\n  \"dedupSimilarityThreshold\": 0.85,\n\n  // Paths (usually auto-detected)\n  \"cassPath\": \"cass\",\n  \"remoteCass\": {\n    \"enabled\": false,\n    \"hosts\": []\n  },\n  \"playbookPath\": \"~/.cass-memory/playbook.yaml\",\n  \"diaryDir\": \"~/.cass-memory/diary\"\n}\n```\n\n### Configuration Options Explained\n\n#### LLM Settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `provider` | `\"anthropic\"` | LLM provider: `anthropic`, `openai`, `google` |\n| `model` | `\"claude-sonnet-4-20250514\"` | Model for reflection |\n| `baseUrl` | _(unset)_ | Custom base URL for OpenAI-compatible gateways (OpenRouter, Z.AI, Azure, etc.) |\n| `disableStructuredOutputs` | `false` | Opt-in escape hatch for OpenAI strict structured-outputs mode. The reflect/audit/validate Zod schemas are written to be strict-compliant, but if you hit `cm reflect` returning zero deltas with \"Invalid JSON response\" warnings on a particular gateway/model combination (see #47), flipping this to `true` falls back to plain JSON mode while still applying the schemas as a post-hoc validator. Leave `false` unless you've confirmed strict-mode is the failure surface. |\n| `budget.dailyLimit` | `0.10` | Max daily LLM spend (USD) |\n| `budget.monthlyLimit` | `2.00` | Max monthly LLM spend (USD) |\n| `budget.warningThreshold` | `80` | Percentage before warning |\n\n#### Scoring Settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `scoring.decayHalfLifeDays` | `90` | Days for feedback to decay to half value |\n| `scoring.harmfulMultiplier` | `4` | Weight harmful feedback N× more than helpful |\n| `scoring.minFeedbackForActive` | `3` | Min feedback to consider bullet \"active\" |\n| `scoring.minHelpfulForProven` | `10` | Min helpful marks for \"proven\" status |\n| `scoring.maxHarmfulRatioForProven` | `0.1` | Max harmful ratio for \"proven\" (10%) |\n\n#### Context Settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `maxBulletsInContext` | `50` | Max rules to return in context |\n| `maxHistoryInContext` | `10` | Max history snippets to return |\n| `sessionLookbackDays` | `7` | Days to search for related sessions |\n| `minRelevanceScore` | `0.1` | Min relevance to include a bullet |\n\n#### Privacy Settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `crossAgent.enabled` | `false` | Enable cross-agent diary enrichment |\n| `crossAgent.consentGiven` | `false` | Explicit consent flag |\n| `crossAgent.agents` | `[]` | Allowlist; empty means \"all agents\" |\n| `crossAgent.auditLog` | `true` | Log enrichment events |\n\n#### Remote History (SSH)\n\nRemote cass is **opt-in** and queries other machines via SSH (using your existing SSH config/keys). Remote hits are tagged with `historySnippets[].origin.kind=\"remote\"` and `origin.host`.\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `remoteCass.enabled` | `false` | Enable SSH-based remote cass history |\n| `remoteCass.hosts` | `[]` | List of SSH targets: `{ host: \"workstation\", label?: \"work\" }` |\n\n#### Semantic Search Settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `semanticSearchEnabled` | `false` | Enable embedding-based search |\n| `semanticWeight` | `0.6` | Weight of semantic vs keyword (0-1) |\n| `embeddingModel` | `Xenova/all-MiniLM-L6-v2` | Transformer model |\n| `embeddingBackend` | `xenova` | Embedding backend: `xenova` (local WASM) or `ollama` |\n| `ollamaBaseUrl` | `http://localhost:11434` | Base URL when `embeddingBackend: \"ollama\"` |\n| `dedupSimilarityThreshold` | `0.85` | Threshold for duplicate detection |\n\n##### How do I tell whether semantic search actually ran?\n\nThe `cm context` command emits a `semanticMode` field in JSON/TOON output\n(one of `\"semantic\"` or `\"keyword\"`). When the user asked for semantic\nbut the runtime could not provide it, `semanticError` explains why:\n\n```bash\n$ cm context \"optimize API latency\" --json | jq '.data | {semanticMode, semanticError}'\n{ \"semanticMode\": \"semantic\", \"semanticError\": null }\n```\n\nIn human output, a yellow warning banner is printed whenever semantic\nwas requested but unavailable — no more silent fallback.\n\n##### Troubleshooting: \"Semantic search unavailable\" in the prebuilt binary\n\nReleases ≤ v0.2.5 shipped a prebuilt binary that could not locate its\nbundled WASM runtime inside Bun's virtual filesystem. This was fixed in\nv0.2.6 (see issue #42): the onnxruntime-web WASM files are now embedded\nvia Bun's `type: \"file\"` imports and wired up at startup. If you see\n`ENOENT: ... /$bunfs/dist/ort-wasm-*.wasm` on an older binary, upgrade:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh | bash -s -- --easy-mode\n```\n\nAlternatively, point cass-memory at a local Ollama daemon (no WASM):\n\n```json\n{\n  \"semanticSearchEnabled\": true,\n  \"embeddingBackend\": \"ollama\",\n  \"embeddingModel\": \"all-minilm\"\n}\n```\n\n### Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `ANTHROPIC_API_KEY` | API key for Anthropic (Claude) |\n| `OPENAI_API_KEY` | API key for OpenAI |\n| `GOOGLE_GENERATIVE_AI_API_KEY` | API key for Google Gemini |\n| `CASS_PATH` | Path to cass binary |\n| `CASS_MEMORY_LLM` | Set to `none` for LLM-free mode |\n\n---\n\n## 🔌 MCP Server\n\nRun cass-memory as an MCP (Model Context Protocol) HTTP server for programmatic agent integration.\nThe transport is HTTP-only (no stdio or SSE):\n\n```bash\n# Local-only by default (recommended) — listens on 127.0.0.1:8765\ncm serve\n\n# Explicit port\ncm serve --port 9000\n\n# If binding to a non-loopback host, set an auth token\nMCP_HTTP_TOKEN=\"\u003crandom\u003e\" cm serve --host 0.0.0.0 --port 8765\n```\n\nWhen `MCP_HTTP_TOKEN` is set, clients must send either `Authorization: Bearer \u003ctoken\u003e` or `X-MCP-Token: \u003ctoken\u003e`.\n\n### Tools Exposed\n\n| Tool | Purpose | Parameters |\n|------|---------|------------|\n| `cm_context` | Get relevant rules + history for a task | `task: string, limit?: number, top?: number (deprecated), history?: number, days?: number, workspace?: string` |\n| `cm_feedback` | Record helpful/harmful feedback | `bulletId: string, helpful?: boolean, harmful?: boolean, reason?: string, session?: string` |\n| `cm_outcome` | Record a session outcome with rules used | `sessionId: string, outcome: \"success\" \\| \"failure\" \\| \"mixed\" \\| \"partial\", rulesUsed?: string[]` |\n| `memory_search` | Search playbook bullets and/or cass history | `query: string, scope?: \"playbook\" \\| \"cass\" \\| \"both\", limit?: number, days?: number` |\n| `memory_reflect` | Trigger reflection on recent sessions | `days?: number, maxSessions?: number, dryRun?: boolean, workspace?: string, session?: string` |\n\n### Resources Exposed\n\n| URI | Purpose |\n|-----|---------|\n| `cm://playbook` | Current playbook state |\n| `cm://diary` | Recent diary entries |\n| `cm://outcomes` | Session outcomes |\n| `cm://stats` | Playbook health metrics |\n\n### MCP Client Configuration\n\n`cm serve` is an **HTTP transport** server (not stdio). Start it first, then\npoint your MCP client at the URL.\n\nFor Claude Code (`~/.config/claude/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"cm\": {\n      \"type\": \"url\",\n      \"url\": \"http://127.0.0.1:8765/\"\n    }\n  }\n}\n```\n\nFor VS Code (Cline/Continue):\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"cass-memory\": {\n        \"type\": \"url\",\n        \"url\": \"http://127.0.0.1:8765/\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🧠 Architecture \u0026 Engineering\n\n### System Overview\n\n```mermaid\nflowchart TB\n    subgraph Sources[\"Agent Sources (Episodic)\"]\n        CC[Claude Code]\n        CX[Codex]\n        CR[Cursor]\n        AD[Aider]\n        PI[PI]\n        GM[Gemini]\n    end\n\n    subgraph CASS[\"cass Engine\"]\n        IDX[Search Index]\n        NRM[Normalizers]\n    end\n\n    subgraph Memory[\"cass-memory\"]\n        GEN[Generator]\n        REF[Reflector]\n        VAL[Validator]\n        CUR[Curator]\n        PB[(Playbook)]\n        DY[(Diary)]\n    end\n\n    subgraph Consumers[\"Consumers\"]\n        CLI[CLI]\n        MCP[MCP Server]\n        API[JSON API]\n    end\n\n    CC --\u003e NRM\n    CX --\u003e NRM\n    CR --\u003e NRM\n    AD --\u003e NRM\n    PI --\u003e NRM\n    GM --\u003e NRM\n    NRM --\u003e IDX\n\n    IDX --\u003e GEN\n    DY --\u003e REF\n    REF --\u003e VAL\n    VAL --\u003e CUR\n    CUR --\u003e PB\n\n    PB --\u003e GEN\n    GEN --\u003e CLI\n    GEN --\u003e MCP\n    GEN --\u003e API\n```\n\n### Directory Structure\n\n```\n~/.cass-memory/                  # Global (user-level)\n├── config.json                  # User configuration\n├── playbook.yaml                # Personal playbook\n├── diary/                       # Session summaries\n│   ├── d-abc123.json\n│   └── d-def456.json\n├── outcomes/                    # Session outcomes\n│   └── YYYY-MM/\n│       └── outcome-\u003ctimestamp\u003e.json\n├── blocked.log                  # Deprecated content hashes\n├── privacy-audit.jsonl          # Cross-agent enrichment audit trail\n├── context-log.jsonl            # Context usage tracking\n├── processed-sessions.jsonl     # Reflection progress log\n└── usage.jsonl                  # LLM cost tracking\n\n.cass/                           # Project-level (in repo)\n├── config.json                  # Project-specific overrides\n├── playbook.yaml                # Project-specific rules\n├── blocked.yaml                 # Anti-patterns to block\n└── context-log.jsonl            # Local context usage\n```\n\n### Component Responsibilities\n\n| Component | Responsibility | LLM? |\n|-----------|----------------|------|\n| **Generator** | Context hydration before tasks | No |\n| **Reflector** | Pattern extraction from sessions | Yes |\n| **Validator** | Evidence-based rule verification | Yes |\n| **Curator** | Deterministic playbook management | **No** |\n| **Scorer** | Decay-adjusted effectiveness calculation | No |\n| **MCP Server** | Protocol bridge for agent integration | No |\n\n### Why Curator Has No LLM\n\nThis is the most important architectural decision:\n\n1. **Prevents context collapse**: LLMs iteratively refining their own outputs tend to drift toward generic, less useful content\n2. **Ensures reproducibility**: Same inputs always produce same outputs\n3. **Reduces costs**: Curation runs frequently; LLM calls would be expensive\n4. **Enables auditing**: Deterministic logic is easier to debug and trust\n\nThe LLM's job is to **propose** patterns. The curator's job is to **manage** them according to explicit rules.\n\n### Concurrency Safety\n\nMultiple processes may access shared files (playbook, trauma registry, diary entries) simultaneously. `cass-memory` uses atomic file locking to prevent corruption:\n\n```\nProcess A                    Lock Directory              Process B\n┌─────────────┐             ┌─────────────┐             ┌─────────────┐\n│ mkdir lock/ │──────────▶  │ .lock.d/    │  ◀──────────│ mkdir lock/ │\n│ (succeeds)  │             │  ├── pid    │             │ (EEXIST!)   │\n│             │             │  └── owner  │             │ retry...    │\n│ write file  │             │             │             │             │\n│ rmdir lock/ │──────────▶  │ (deleted)   │  ◀──────────│ mkdir lock/ │\n│             │             │ .lock.d/    │             │ (succeeds)  │\n└─────────────┘             └─────────────┘             └─────────────┘\n```\n\n**Key features:**\n- **Atomic acquisition**: Uses `mkdir()` which is atomic across all operating systems\n- **Heartbeat**: Long operations refresh the lock timestamp every 10 seconds\n- **Stale detection**: Locks older than 30 seconds without an active heartbeat are automatically cleaned up\n- **Orphan cleanup**: Detects dead PIDs and removes abandoned locks\n- **Ownership verification**: Stores random UUID to prevent accidental lock theft\n\nThis ensures that even with multiple agents or background jobs running concurrently, data files remain consistent.\n\n---\n\n## 🔬 Deep Dive: Core Algorithms\n\n### Relevance Scoring\n\nWhen retrieving context for a task, bullets are scored by relevance:\n\n```typescript\nfunction scoreRelevance(bullet: PlaybookBullet, task: string): number {\n  // 1. Keyword overlap (fast)\n  const taskKeywords = extractKeywords(task);\n  const bulletKeywords = extractKeywords(bullet.content);\n  const keywordOverlap = intersection(taskKeywords, bulletKeywords).size\n    / union(taskKeywords, bulletKeywords).size;\n\n  // 2. Category bonus\n  const categoryBonus = taskCategories.includes(bullet.category) ? 0.2 : 0;\n\n  // 3. Semantic similarity (optional, if enabled)\n  let semanticScore = 0;\n  if (config.semanticSearchEnabled \u0026\u0026 bullet.embedding) {\n    const taskEmbedding = await embed(task);\n    semanticScore = cosineSimilarity(taskEmbedding, bullet.embedding);\n  }\n\n  // 4. Combined score\n  const keywordWeight = config.semanticSearchEnabled ? (1 - config.semanticWeight) : 1;\n  const semanticWeight = config.semanticSearchEnabled ? config.semanticWeight : 0;\n\n  return (keywordOverlap * keywordWeight)\n       + (semanticScore * semanticWeight)\n       + categoryBonus;\n}\n\nfunction extractKeywords(text: string): Set\u003cstring\u003e {\n  const stopwords = new Set(['the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', ...]);\n\n  return new Set(\n    text.toLowerCase()\n      .replace(/[^a-z0-9\\s]/g, ' ')\n      .split(/\\s+/)\n      .filter(word =\u003e word.length \u003e 2 \u0026\u0026 !stopwords.has(word))\n  );\n}\n```\n\n### Duplicate Detection\n\nPreventing duplicate rules uses both hash-based and semantic approaches:\n\n```typescript\nfunction findDuplicate(playbook: Playbook, newRule: ProposedRule): PlaybookBullet | null {\n  // 1. Exact hash match (fast)\n  const newHash = hashContent(normalize(newRule.content));\n  for (const bullet of playbook.bullets) {\n    if (hashContent(normalize(bullet.content)) === newHash) {\n      return bullet;\n    }\n  }\n\n  // 2. Semantic similarity (if embeddings available)\n  if (config.semanticSearchEnabled \u0026\u0026 newRule.embedding) {\n    for (const bullet of playbook.bullets) {\n      if (bullet.embedding) {\n        const similarity = cosineSimilarity(newRule.embedding, bullet.embedding);\n        if (similarity \u003e config.dedupSimilarityThreshold) {\n          return bullet;\n        }\n      }\n    }\n  }\n\n  return null;\n}\n\nfunction normalize(content: string): string {\n  return content\n    .toLowerCase()\n    .replace(/[^a-z0-9\\s]/g, '')\n    .replace(/\\s+/g, ' ')\n    .trim();\n}\n```\n\n### Conflict Detection\n\nFinding contradicting rules:\n\n```typescript\nfunction findConflicts(playbook: Playbook, newRule: ProposedRule): PlaybookBullet[] {\n  const conflicts: PlaybookBullet[] = [];\n\n  // Check for direct contradictions\n  const newNormalized = normalize(newRule.content);\n  const newNegated = negateRule(newNormalized);\n\n  for (const bullet of playbook.bullets.filter(b =\u003e b.state === 'active')) {\n    const bulletNormalized = normalize(bullet.content);\n\n    // Check if new rule is negation of existing\n    if (bulletNormalized === newNegated || normalize(negateRule(bullet.content)) === newNormalized) {\n      conflicts.push(bullet);\n      continue;\n    }\n\n    // Semantic contradiction check\n    if (config.semanticSearchEnabled) {\n      const contradictionScore = await checkSemanticContradiction(newRule, bullet);\n      if (contradictionScore \u003e 0.8) {\n        conflicts.push(bullet);\n      }\n    }\n  }\n\n  return conflicts;\n}\n\nfunction negateRule(rule: string): string {\n  const negations: [RegExp, string][] = [\n    [/^always /i, 'never '],\n    [/^never /i, 'always '],\n    [/^do /i, \"don't \"],\n    [/^don't /i, 'do '],\n    [/^use /i, \"don't use \"],\n    [/^avoid /i, 'use '],\n  ];\n\n  for (const [pattern, replacement] of negations) {\n    if (pattern.test(rule)) {\n      return rule.replace(pattern, replacement);\n    }\n  }\n\n  return `don't ${rule}`;\n}\n```\n\n### cass Integration\n\nThe cass search wrapper handles JSON parsing and fallback modes:\n\n```typescript\nasync function safeCassSearch(\n  query: string,\n  options: CassSearchOptions,\n  cassPath?: string,\n  config?: Config\n): Promise\u003cCassHit[]\u003e {\n  // Check cass availability\n  const availability = await handleCassUnavailable({ cassPath });\n  if (!availability.canContinue) {\n    return [];\n  }\n\n  if (availability.fallbackMode === 'playbook-only') {\n    // No cass available - return empty, let caller use playbook only\n    return [];\n  }\n\n  // Build command\n  const args = ['search', query, '--robot', '--limit', String(options.limit || 10)];\n  if (options.days) args.push('--days', String(options.days));\n  if (options.agent) args.push('--agent', options.agent);\n\n  // Execute\n  const result = await execAsync(`${availability.resolvedCassPath} ${args.join(' ')}`);\n\n  // Parse output - handle both array and wrapped object formats\n  const rawHits = parseCassJsonOutput(result.stdout);\n\n  // cass search --robot returns { count, hits, ... } wrapper\n  let hitsArray: unknown[];\n  if (Array.isArray(rawHits)) {\n    hitsArray = rawHits;\n  } else if (rawHits \u0026\u0026 typeof rawHits === 'object' \u0026\u0026 Array.isArray((rawHits as any).hits)) {\n    hitsArray = (rawHits as any).hits;\n  } else {\n    hitsArray = [rawHits];\n  }\n\n  // Validate with Zod schema\n  return hitsArray.map(h =\u003e CassHitSchema.parse(h));\n}\n```\n\n### Embedding Generation\n\nFor semantic search (when enabled):\n\n```typescript\nimport { pipeline } from '@xenova/transformers';\n\nlet embeddingPipeline: any = null;\n\nasync function getEmbedding(text: string): Promise\u003cnumber[]\u003e {\n  if (!embeddingPipeline) {\n    embeddingPipeline = await pipeline(\n      'feature-extraction',\n      config.embeddingModel || 'Xenova/all-MiniLM-L6-v2'\n    );\n  }\n\n  const result = await embeddingPipeline(text, {\n    pooling: 'mean',\n    normalize: true\n  });\n\n  return Array.from(result.data);\n}\n\nfunction cosineSimilarity(a: number[], b: number[]): number {\n  if (a.length !== b.length) throw new Error('Vectors must have same length');\n\n  let dotProduct = 0;\n  let normA = 0;\n  let normB = 0;\n\n  for (let i = 0; i \u003c a.length; i++) {\n    dotProduct += a[i] * b[i];\n    normA += a[i] * a[i];\n    normB += b[i] * b[i];\n  }\n\n  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));\n}\n```\n\n---\n\n## 🔒 Privacy \u0026 Security\n\n### Local-First Design\n\n- **All data stays on your machine** - No cloud sync, no telemetry\n- **No network calls** except optional LLM API calls for reflection\n- **Cross-agent enrichment is opt-in** - Must explicitly enable with consent\n\n### Data Access Patterns\n\n**What cass-memory reads:**\n- Agent session files (via cass)\n- Local playbook and diary files\n- Environment variables (configuration only)\n\n**What cass-memory writes:**\n- `~/.cass-memory/` directory contents\n- `.cass/` directory in repos (if project-level config)\n\n**What cass-memory NEVER does:**\n- Modify source code files\n- Make network requests (except LLM API when configured)\n- Execute code from playbook content\n- Access files outside known directories\n\n### Secret Sanitization\n\nBefore any data is processed, it's sanitized to remove sensitive content:\n\n```typescript\nconst DEFAULT_SECRET_PATTERNS = [\n  // API Keys\n  /sk-[a-zA-Z0-9]{20,}/g,           // OpenAI\n  /sk-ant-[a-zA-Z0-9-]{20,}/g,      // Anthropic\n  /AKIA[A-Z0-9]{16}/g,              // AWS\n  /AIza[a-zA-Z0-9_-]{35}/g,         // Google\n\n  // Tokens\n  /ghp_[a-zA-Z0-9]{36}/g,           // GitHub PAT\n  /ghu_[a-zA-Z0-9]{36}/g,           // GitHub user token\n  /eyJ[a-zA-Z0-9_-]+\\.[a-zA-Z0-9_-]+\\.[a-zA-Z0-9_-]+/g,  // JWT\n\n  // Passwords\n  /password\\s*[=:]\\s*['\"][^'\"]+['\"]/gi,\n  /secret\\s*[=:]\\s*['\"][^'\"]+['\"]/gi,\n\n  // Environment variables with sensitive names\n  /\\b(API_KEY|SECRET|PASSWORD|TOKEN|PRIVATE_KEY)\\s*=\\s*\\S+/gi,\n];\n\nfunction sanitizeContent(content: string, extraPatterns?: RegExp[]): string {\n  let sanitized = content;\n\n  const patterns = [...DEFAULT_SECRET_PATTERNS, ...(extraPatterns || [])];\n\n  for (const pattern of patterns) {\n    sanitized = sanitized.replace(pattern, '[REDACTED]');\n  }\n\n  return sanitized;\n}\n```\n\n### Privacy Controls\n\n```bash\n# Check current settings\ncm privacy status\n\n# Enable cross-agent enrichment (requires explicit consent)\ncm privacy enable\n\n# Disable cross-agent enrichment\ncm privacy disable\n```\n\nWhen cross-agent enrichment is enabled:\n- An audit log is written to `privacy-audit.jsonl`\n- You can filter by agent with `crossAgent.agents` allowlist\n- Consent date is recorded for compliance\n\n### Threat Model\n\n**cass-memory assumes:**\n- The local filesystem is trusted\n- The user running `cm` should have access to all indexed content\n- LLM API providers (when configured) are trusted with sanitized content\n\n**cass-memory does NOT protect against:**\n- Root/admin access to the machine\n- Memory forensics while running\n- Physical access to the storage device\n- Malicious LLM providers (use trusted providers only)\n\n---\n\n## 🛡️ Trauma Guard: Safety System\n\n### The \"Hot Stove\" Principle\n\nAI coding agents are powerful, but that power comes with risk. A mistyped `rm -rf`, an accidental `git push --force`, or a database `DROP TABLE` can cause catastrophic damage. The **Trauma Guard** system learns from past incidents and prevents them from recurring—like how touching a hot stove once teaches you not to do it again.\n\n### How It Works\n\n```\nSession History              Trauma Registry              Runtime Guard\n┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐\n│ rm -rf /* (oops)│ ──────▶ │ Pattern: rm -rf │ ──────▶ │ BLOCKED: This   │\n│ \"sorry, I made  │  scan   │ Severity: FATAL │  hook   │ command matches │\n│  a mistake...\"  │         │ Session: abc123 │         │ a trauma pattern│\n└─────────────────┘         └─────────────────┘         └─────────────────┘\n```\n\n1. **Detection**: Scans session history for dangerous commands combined with \"apology\" signals (errors, \"oops\", \"sorry\", rollbacks)\n2. **Registration**: Stores dangerous patterns in a registry with severity and provenance\n3. **Prevention**: Hooks into Claude Code and Git to block matching commands before execution\n\n### Built-in Doom Patterns\n\nThe system ships with 20+ predefined patterns covering common catastrophic operations:\n\n| Category | Examples |\n|----------|----------|\n| **Filesystem** | `rm -rf /`, `rm -rf ~`, recursive deletes without confirmation |\n| **Database** | `DROP DATABASE`, `TRUNCATE`, `DELETE FROM` without WHERE |\n| **Git** | `git push --force` to main/master, `git reset --hard` |\n| **Infrastructure** | `terraform destroy -auto-approve`, `kubectl delete namespace` |\n| **Cloud** | `aws s3 rm --recursive`, destructive CloudFormation operations |\n\n### CLI Commands\n\n```bash\n# View all active trauma patterns\ncm trauma list\n\n# Add a custom dangerous pattern\ncm trauma add \"DELETE FROM users\" --description \"Mass user deletion\" --severity critical\n\n# Temporarily disable a pattern (when you really need to run it)\ncm trauma heal t-abc123 --reason \"Intentional cleanup\"\n\n# Permanently remove a pattern\ncm trauma remove t-abc123\n\n# Import patterns from a file\ncm trauma import team-traumas.yaml\n\n# Scan recent sessions for potential traumas\ncm trauma scan --days 30\n```\n\n### Installing the Guard Hooks\n\nThe trauma guard requires hooks to intercept commands before execution:\n\n```bash\n# Install Claude Code hook (intercepts Bash commands)\ncm guard --install\n\n# Install Git pre-commit hook (scans commits)\ncm guard --git\n\n# Install both\ncm guard --install --git\n\n# Check installation status\ncm guard --status\n```\n\n**What happens when a pattern matches:**\n\n```\n🔥 HOT STOVE: Command blocked by trauma guard\n\n  Pattern: rm -rf /*\n  Severity: FATAL\n  Reason: Recursive delete of root filesystem\n\n  This pattern was marked dangerous after session:\n    ~/.claude/sessions/session-abc123.jsonl\n\n  To proceed anyway (use extreme caution):\n    cm trauma heal t-abc123 --reason \"your justification\"\n```\n\n### Trauma Storage\n\nPatterns are stored at two levels:\n\n| Scope | Location | Purpose |\n|-------|----------|---------|\n| **Global** | `~/.cass-memory/traumas.jsonl` | Personal patterns across all projects |\n| **Project** | `.cass/traumas.jsonl` | Project-specific patterns (commit to repo) |\n\nProject patterns can be committed to your repository, creating shared team knowledge about dangerous operations specific to that codebase.\n\n### Pattern Lifecycle\n\n```\n┌────────────┐     heal      ┌────────────┐     activate    ┌────────────┐\n│   ACTIVE   │ ───────────▶  │   HEALED   │ ────────────▶   │   ACTIVE   │\n│  (blocking)│               │(temp bypass)│                │  (blocking)│\n└────────────┘               └────────────┘                 └────────────┘\n      │                                                           ▲\n      │ remove                                                    │\n      ▼                                                           │\n┌────────────┐                                                    │\n│  DELETED   │ ───────────────────────────────────────────────────┘\n│ (can re-add)│           manual add\n└────────────┘\n```\n\n- **Active**: Pattern blocks matching commands\n- **Healed**: Temporarily bypassed (with reason and timestamp)\n- **Deleted**: Removed from registry (can be re-added later)\n\n### Integration with Claude Code\n\nWhen installed via `cm guard --install`, the trauma guard integrates as a Claude Code pre-tool hook:\n\n```json\n// .claude/settings.json (auto-configured)\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\".claude/hooks/trauma_guard.py\"]\n      }\n    ]\n  }\n}\n```\n\nThe hook runs before every Bash command, checking against active patterns. If a match is found, the command is blocked with an explanation—the agent never executes the dangerous operation.\n\n### Why This Matters\n\nTraditional safety approaches rely on:\n- **Allowlists**: Too restrictive, break legitimate workflows\n- **Manual review**: Doesn't scale, humans miss things\n- **Hope**: Eventually fails catastrophically\n\nTrauma Guard is different:\n- **Learning**: Patterns come from actual incidents, not theoretical risks\n- **Contextual**: Project-specific patterns for project-specific risks\n- **Recoverable**: Healing allows intentional operations with audit trail\n- **Shared**: Team patterns create collective institutional memory\n\n---\n\n## 📊 Performance Characteristics\n\n### Benchmarked Operations\n\n| Operation | Typical Latency | Conditions |\n|-----------|-----------------|------------|\n| `cm context` (cached) | 50-150ms | Warm cache, \u003c100 bullets |\n| `cm context` (cold) | 200-500ms | First run, cass search |\n| `cm context` (no cass) | 30-80ms | Playbook-only mode |\n| `cm reflect` (1 session) | 5-15s | Depends on session length |\n| `cm reflect` (5 sessions) | 20-60s | Parallel diary, serial reflect |\n| `cm playbook list` | \u003c50ms | Local file read |\n| `cm similar` (keyword) | 20-50ms | No embeddings |\n| `cm similar` (semantic) | 100-300ms | With embeddings |\n\n### Memory Usage\n\n| Component | Typical Size | Notes |\n|-----------|--------------|-------|\n| Base process | ~50MB | Bun runtime + application |\n| Embedding model (loaded) | ~100MB | Only when semantic search enabled |\n| Playbook (1000 bullets) | ~5MB | YAML + embeddings |\n| Diary cache | ~10MB | Recent entries |\n\n### Scaling Characteristics\n\n| Bullet Count | Context Latency | Recommendation |\n|--------------|-----------------|----------------|\n| \u003c100 | \u003c100ms | Optimal |\n| 100-500 | 100-300ms | Good |\n| 500-1000 | 300-500ms | Consider pruning stale rules |\n| \u003e1000 | \u003e500ms | Use `cm top` to focus on best rules |\n\n### LLM Cost Estimates\n\n| Operation | Typical Cost | Notes |\n|-----------|--------------|-------|\n| Reflect (1 session) | $0.01-0.05 | Depends on session length |\n| Reflect (7 days, 5 sessions) | $0.05-0.20 | Batched processing |\n| Validate (1 rule) | $0.005-0.01 | Short prompts |\n\nWith default budget limits ($0.10/day, $2.00/month), you can typically:\n- Reflect on 5-10 sessions per day\n- Validate 10-20 new rules per day\n\n---\n\n## 📚 Starter Playbooks\n\nStarting with an empty playbook is daunting. **Starter playbooks** provide curated collections of best practices for specific tech stacks, giving you a solid foundation to build upon.\n\n### Built-in Starters\n\n```bash\n# List all available starters\ncm starters\n\n# Initialize with a starter\ncm init --starter typescript\n\n# Apply a starter to an existing playbook\ncm playbook bootstrap react\n```\n\n| Starter | Focus | Rules |\n|---------|-------|-------|\n| **general** | Universal best practices | 5 |\n| **typescript** | TypeScript/Node.js patterns | 4 |\n| **react** | React/Next.js development | 4 |\n| **python** | Python/FastAPI/Django | 4 |\n| **node** | Node.js/Express services | 4 |\n| **rust** | Rust service patterns | 4 |\n\n### What's In a Starter\n\nEach starter contains battle-tested rules with proper metadata:\n\n**General Starter** (universal):\n- Keep functions small and focused (single responsibility)\n- Validate inputs at system boundaries\n- Implement graceful shutdown for services\n- Add observability from the start\n- Set timeouts on all external calls\n\n**React Starter**:\n- Always specify dependency arrays in useEffect\n- Use unique, stable keys for list items\n- Check `typeof window` before browser-only code\n- Include ARIA attributes for accessibility\n\n**Python Starter**:\n- Use type hints for function signatures\n- Prefer dependency injection over global state\n- Set explicit timeouts on HTTP clients\n- Use structured logging (JSON format)\n\n**Node Starter**:\n- Wrap async route handlers in try/catch\n- Set timeouts on HTTP requests and DB queries\n- Validate environment variables at startup\n- Handle SIGTERM gracefully for container orchestration\n\n**Rust Starter**:\n- Use `?` operator and thiserror for error handling\n- Run clippy and rustfmt before commits\n- Avoid blocking in async context\n- Use structured tracing for observability\n\n### Creating Custom Starters\n\nCreate YAML files in `~/.cass-memory/starters/`:\n\n```yaml\n# ~/.cass-memory/starters/django.yaml\nname: django\ndescription: Django web framework best practices\nbullets:\n  - content: \"Always use Django's ORM for database operations\"\n    category: database\n    maturity: established\n    tags: [django, orm, database]\n\n  - content: \"Run migrations before deploying\"\n    category: deployment\n    maturity: proven\n    tags: [django, migrations, deploy]\n\n  - content: \"Use Django's CSRF protection on all POST forms\"\n    category: security\n    maturity: proven\n    tags: [django, security, csrf]\n\n  - content: \"Configure ALLOWED_HOSTS in production settings\"\n    category: security\n    maturity: established\n    tags: [django, security, config]\n```\n\nCustom starters are discovered automatically and appear in `cm starters`.\n\n### Starter vs Reflection\n\n| Source | When to Use | Trust Level |\n|--------|-------------|-------------|\n| **Starters** | Bootstrap new projects | Pre-validated, established |\n| **Reflection** | Learn from your sessions | Candidate until proven |\n\nStarters give you a head start. Reflection adds project-specific learning. Use both for a comprehensive playbook.\n\n---\n\n## 🔧 Extensibility: Adding New Components\n\n### Adding a New Starter Playbook\n\nCreate a file at `src/starters/\u003cname\u003e.yaml`:\n\n```yaml\n# src/starters/django.yaml\nmetadata:\n  name: django\n  description: Django web framework best practices\n  version: \"1.0\"\n  tags: [python, django, web]\n\nbullets:\n  - content: \"Always use Django's ORM for database operations\"\n    category: database\n    scope: framework\n    kind: stack_pattern\n    maturity: established\n\n  - content: \"Run migrations before deploying\"\n    category: deployment\n    scope: framework\n    kind: workflow_rule\n    maturity: proven\n```\n\nRegister in `src/commands/starters.ts`:\n\n```typescript\nconst STARTERS = ['typescript', 'react', 'python', 'go', 'django'];  // Add here\n```\n\n### Adding a New Scoring Factor\n\nExtend the scoring calculation in `src/scoring.ts`:\n\n```typescript\ninterface ScoringConfig {\n  decayHalfLifeDays: number;\n  harmfulMultiplier: number;\n  // Add new factor\n  recencyBonus: number;  // Boost for recently created rules\n}\n\nfunction getEffectiveScore(bullet: PlaybookBullet, config: ScoringConfig): number {\n  // Existing decay calculation...\n  const baseScore = decayedHelpful - (config.harmfulMultiplier * decayedHarmful);\n\n  // Add recency bonus for new rules\n  const daysSinceCreation = daysSince(bullet.createdAt);\n  const recencyFactor = daysSinceCreation \u003c 30 ? config.recencyBonus : 0;\n\n  return baseScore + recencyFactor;\n}\n```\n\n### Adding a New MCP Tool\n\nAdd tool definition in `src/mcp/tools.ts`:\n\n```typescript\nconst tools = {\n  // Existing tools...\n\n  memory_bulk_feedback: {\n    description: 'Record feedback on multiple rules at once',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        feedback: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              bulletId: { type: 'string' },\n              type: { type: 'string', enum: ['helpful', 'harmful'] },\n              reason: { type: 'string' }\n            },\n            required: ['bulletId', 'type']\n          }\n        }\n      },\n      required: ['feedback']\n    },\n    handler: async (args: { feedback: FeedbackItem[] }) =\u003e {\n      const results = [];\n      for (const item of args.feedback) {\n        const result = await recordFeedback(item.bulletId, item.type, item.reason);\n        results.push(result);\n      }\n      return { results };\n    }\n  }\n};\n```\n\n### Adding a New Output Format\n\nExtend `cm project` for new export formats:\n\n```typescript\n// src/commands/project.ts\n\nconst FORMATS = {\n  'agents.md': formatForAgentsMd,\n  'claude.md': formatForClaudeMd,\n  'json': formatAsJson,\n  // Add new format\n  'notion': formatForNotion,\n};\n\nfunction formatForNotion(playbook: Playbook): string {\n  // Notion-compatible markdown with toggle blocks\n  let output = '# Playbook Rules\\n\\n';\n\n  for (const bullet of playbook.bullets.filter(b =\u003e b.state === 'active')) {\n    output += `\u003cdetails\u003e\\n`;\n    output += `\u003csummary\u003e${bullet.content}\u003c/summary\u003e\\n\\n`;\n    output += `- **Category**: ${bullet.category}\\n`;\n    output += `- **Maturity**: ${bullet.maturity}\\n`;\n    output += `- **Score**: ${bullet.effectiveScore?.toFixed(2)}\\n`;\n    if (bullet.reasoning) {\n      output += `- **Reasoning**: ${bullet.reasoning}\\n`;\n    }\n    output += `\u003c/details\u003e\\n\\n`;\n  }\n\n  return output;\n}\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `cass not found` | cass CLI not installed | Install from [cass repo](https://github.com/Dicklesworthstone/coding_agent_session_search) |\n| `cass search failed` | cass index missing or corrupt | Run `cass index --full` |\n| `API key missing` | No LLM API key set | Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY` |\n| `Playbook corrupt` | Invalid YAML in playbook | Run `cm doctor --fix` |\n| `Rate limited` | Too many LLM requests | Wait for retry (exponential backoff is automatic) |\n| `Budget exceeded` | Daily/monthly limit hit | Check `cm usage`, adjust limits in config |\n| `Config invalid` | Malformed config file | Validate JSON syntax, check schema |\n| `Session not found` | Path doesn't exist | Verify path with `cass sessions` |\n| `Embedding model failed` | Model download issue | Check network, try `cm doctor --fix` |\n\n### Diagnostic Commands\n\n```bash\n# Check system health\ncm doctor --json\n\n# Auto-fix common issues\ncm doctor --fix\n\n# Check LLM budget status\ncm usage\n\n# List playbook health\ncm stats --json\n\n# Show bullet provenance\ncm why \u003cbullet-id\u003e\n\n# Verify cass integration\ncm context \"test\" --json  # Check degraded field\n```\n\n### Recovery Steps\n\n**Corrupted playbook:**\n```bash\n# 1. Check for backup\nls ~/.cass-memory/playbook.yaml.backup.*\n\n# 2. Run doctor to diagnose\ncm doctor\n\n# 3. If needed, re-initialize (creates backups)\ncm init --force\n```\n\n**Missing API key:**\n```bash\n# For Anthropic (recommended)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# For OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Add to shell profile for persistence\necho 'export ANTHROPIC_API_KEY=\"...\"' \u003e\u003e ~/.zshrc\n```\n\n**LLM-free mode:**\n```bash\n# Run without LLM calls (limited functionality)\nCASS_MEMORY_LLM=none cm context \"task\" --json\n```\n\n**cass integration issues:**\n```bash\n# Check cass directly\ncass health\n\n# Rebuild cass index if needed\ncass index --full\n\n# Test cass-memory integration\ncm doctor --json | jq '.checks[] | select(.category | contains(\"cass\"))'\n```\n\n---\n\n## 🎯 Design Philosophy\n\n### Core Principles\n\n**1. Deterministic Curation (No LLM)**\n\nThe curator stage uses **NO LLM**. This is the most critical design decision:\n- Prevents context collapse from feedback loops\n- Ensures reproducible behavior\n- Avoids expensive redundant LLM calls\n\nLLM extracts patterns (Reflector). Deterministic logic manages them (Curator).\n\n**2. Scientific Validation**\n\nRules aren't accepted on faith. Every new rule must pass an evidence gate:\n- Search cass for sessions where the pattern would apply\n- Count successful vs failed outcomes\n- Only accept rules with positive evidence\n\n**3. Time-Aware Confidence**\n\nKnowledge decays. A rule that was helpful 8 times in January but never validated since:\n- Loses half its confidence by April\n- Loses 75% by July\n- May be auto-deprecated by October\n\nThis prevents stale rules from polluting the playbook.\n\n**4. Fail-Safe Degradation**\n\nEvery external dependency has a fallback:\n- cass unavailable → playbook-only mode\n- LLM unavailable → deterministic reflection\n- Network down → cached embeddings\n- Config corrupt → safe defaults\n\n### Architectural Trade-offs\n\n| Decision | Rationale | Cost |\n|----------|-----------|------|\n| **No LLM in Curator** | Prevents context collapse | Less \"smart\" merging |\n| **90-day decay** | Keeps playbook fresh | Requires ongoing validation |\n| **4x harmful weight** | One mistake is costly | Slower positive learning |\n| **Local-first** | Privacy, speed, offline | No cloud sync |\n| **YAML playbook** | Human-editable, git-friendly | Merge conflicts possible |\n| **Bun runtime** | Fast startup, TypeScript native | Less mature than Node |\n\n### What We Deliberately Avoid\n\n1. **Auto-executing rules** - We advise, never execute\n2. **Cloud sync** - Data stays local by design\n3. **Real-time collaboration** - Different tool category\n4. **Complex UI** - CLI-first for agent consumption\n5. **Proprietary formats** - YAML/JSON for transparency\n\n---\n\n## ⚖️ Comparison with Alternatives\n\n### Why Not Just Comments/Notes?\n\n| Aspect | Manual Notes | cass-memory |\n|--------|--------------|-------------|\n| Cross-agent | Manual sync | Automatic |\n| Confidence tracking | No | Built-in decay |\n| Evidence-based | No | cass validation |\n| Searchable | Depends on format | Always |\n| Auto-learning | No | Yes |\n| Anti-patterns | Manual | Auto-inverted |\n\n### Why Not Just Search cass Directly?\n\n| Aspect | Raw cass | cass-memory |\n|--------|----------|-------------|\n| Distilled rules | No | Yes |\n| Confidence scoring | No | Yes |\n| Anti-patterns | No | Auto-inverted |\n| Task relevance | Manual query | Automatic |\n| Semantic search | No | Optional |\n| Maturity tracking | No | Yes |\n\n**Verdict**: cass is the foundation. cass-memory adds the learning layer.\n\n### Why Not Cursor Rules / Claude Memory?\n\n| Aspect | Vendor Memory | cass-memory |\n|--------|---------------|-------------|\n| Cross-agent | Single vendor | All agents |\n| Local control | Vendor-managed | You own it |\n| Confidence decay | No | Yes |\n| Evidence validation | No | cass-based |\n| Open source | No | Yes |\n| Customizable | Limited | Fully |\n\n**Verdict**: Vendor memory is convenient but siloed. cass-memory unifies all agents.\n\n### Why Not LangChain Memory / MemGPT?\n\n| Aspect | LangChain/MemGPT | cass-memory |\n|--------|------------------|-------------|\n| Focus | General LLM memory | Coding agents specifically |\n| Learning source | User-provided | Auto from sessions |\n| Rules format | Embeddings only | Rules + embeddings |\n| Decay | No | Yes |\n| Anti-patterns | No | Yes |\n| Offline | Limited | Full |\n\n**Verdict**: General memory systems lack coding-specific features like anti-pattern inversion and session outcome tracking.\n\n---\n\n## 🗺️ Roadmap\n\n### Near-Term\n- [ ] Improved semantic search with better embedding models\n- [ ] More starter playbooks (Ruby, Go, Rust, Java)\n- [ ] Better conflict resolution in curation\n- [ ] VS Code extension for inline feedback visualization\n\n### Medium-Term\n- [ ] Team playbook sharing (opt-in, encrypted)\n- [ ] Web dashboard for playbook visualization\n- [ ] Active learning - ask agents for feedback on uncertain rules\n- [ ] Git-based playbook sync across machines\n\n### Long-Term\n- [ ] Federated learning across teams\n- [ ] Automatic rule refinement based on outcomes\n- [ ] Multi-modal rules (diagrams, code snippets)\n- [ ] Integration with more agent platforms\n\n### Non-Goals\n\nThese are explicitly out of scope:\n\n- **Cloud sync** - This is local-first by design\n- **Real-time collaboration** - That's a different tool category\n- **Agent execution** - We search and advise, not execute\n- **Universal knowledge base** - Focus remains on coding agents\n\n---\n\n## 🧪 Development\n\n```bash\ngit clone https://github.com/Dicklesworthstone/cass_memory_system.git\ncd cass_memory_system\nbun install\n\n# Dev with hot reload\nbun --watch run src/cm.ts \u003ccommand\u003e\n\n# Tests\nbun test\nbun run test:watch\nbun run test:coverage\n\n# Type check\nbun run typecheck\n\n# Lint\nbun run lint\n\n# Build all platforms\nbun run build:all\n```\n\n### Testing Categories\n\n| Category | Naming | Run |\n|----------|--------|-----|\n| Unit | `*.test.ts` | `bun run test:unit` |\n| Integration | `*.integration.test.ts` | `bun run test:integration` |\n| E2E | `*.e2e.test.ts` | `bun run test:e2e` |\n| Property | `*.property.test.ts` | `bun run test:property` |\n\nCoverage targets: ~80% lines, 80% functions, 70% branches.\n\n### Build Outputs\n\n| Platform | Output |\n|----------|--------|\n| Linux x64 | `dist/cass-memory-linux-x64` |\n| macOS ARM64 | `dist/cass-memory-macos-arm64` |\n| macOS x64 | `dist/cass-memory-macos-x64` |\n| Windows x64 | `dist/cass-memory-windows-x64.exe` |\n\n---\n\n## 📜 License\n\nMIT License (with OpenAI/Anthropic Rider). See [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **[cass](https://github.com/Dicklesworthstone/coding_agent_session_search)** — The foundation that makes cross-agent search possible\n- **ACE Paper** — The Agentic Context Engineering framework that inspired the pipeline design\n- **Xenova/transformers** — Browser/Node.js transformers for embeddings\n- **Bun** — Fast JavaScript runtime that makes CLI tools snappy\n\n---\n\n\u003e *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDicklesworthstone%2Fcass_memory_system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDicklesworthstone%2Fcass_memory_system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDicklesworthstone%2Fcass_memory_system/lists"}