@strvmarv/total-recall 0.1.0

package/eval/benchmarks/retrieval.jsonl

@@ -0,0 +1,20 @@
+{"query":"which package manager should I use","expected_content_contains":"pnpm","expected_tier":"warm"}
+{"query":"testing strategy database mocking","expected_content_contains":"integration tests","expected_tier":"warm"}
+{"query":"how does authentication work","expected_content_contains":"Passport","expected_tier":"warm"}
+{"query":"deployment pipeline process","expected_content_contains":"staging","expected_tier":"warm"}
+{"query":"test runner framework","expected_content_contains":"vitest","expected_tier":"warm"}
+{"query":"database ORM setup","expected_content_contains":"Drizzle","expected_tier":"warm"}
+{"query":"API error format","expected_content_contains":"RFC 7807","expected_tier":"warm"}
+{"query":"which endpoints need auth","expected_content_contains":"/health","expected_tier":"warm"}
+{"query":"input validation library","expected_content_contains":"zod","expected_tier":"warm"}
+{"query":"what is redis used for","expected_content_contains":"session","expected_tier":"warm"}
+{"query":"git branch naming convention","expected_content_contains":"feat/","expected_tier":"warm"}
+{"query":"environment variable security","expected_content_contains":".env","expected_tier":"warm"}
+{"query":"frontend framework","expected_content_contains":"React","expected_tier":"warm"}
+{"query":"styling approach","expected_content_contains":"Tailwind","expected_tier":"warm"}
+{"query":"how to run migrations","expected_content_contains":"Drizzle Kit","expected_tier":"warm"}
+{"query":"logging format","expected_content_contains":"pino","expected_tier":"warm"}
+{"query":"file upload architecture","expected_content_contains":"S3","expected_tier":"warm"}
+{"query":"background job queue","expected_content_contains":"BullMQ","expected_tier":"warm"}
+{"query":"realtime communication","expected_content_contains":"socket.io","expected_tier":"warm"}
+{"query":"user communication preferences","expected_content_contains":"terse","expected_tier":"warm"}

package/eval/corpus/memories.jsonl

@@ -0,0 +1,20 @@
+{"content":"User prefers pnpm over npm for package management","type":"correction","tags":["tooling","packages"]}
+{"content":"Always use integration tests with real databases, never mock the data layer","type":"preference","tags":["testing","databases"]}
+{"content":"Auth system uses Passport.js with JWT tokens","type":"decision","tags":["auth","architecture"]}
+{"content":"Deploy to staging first via GitHub Actions, production requires manual approval","type":"preference","tags":["deployment","ci"]}
+{"content":"Use vitest as the test runner, not jest","type":"correction","tags":["testing","tooling"]}
+{"content":"Project uses PostgreSQL with Drizzle ORM","type":"decision","tags":["database","orm"]}
+{"content":"Error responses should use RFC 7807 Problem Details format","type":"preference","tags":["api","errors"]}
+{"content":"All API endpoints require authentication except /health and /docs","type":"decision","tags":["api","auth"]}
+{"content":"Use zod for runtime schema validation at API boundaries","type":"preference","tags":["validation","api"]}
+{"content":"Redis is used for session storage and rate limiting only","type":"decision","tags":["redis","architecture"]}
+{"content":"Feature branches should be named feat/TICKET-description","type":"preference","tags":["git","workflow"]}
+{"content":"Never commit .env files, use .env.example as template","type":"correction","tags":["security","git"]}
+{"content":"The frontend uses React with TanStack Router","type":"decision","tags":["frontend","react"]}
+{"content":"CSS uses Tailwind with the project's custom design tokens","type":"decision","tags":["frontend","css"]}
+{"content":"All database migrations go through Drizzle Kit","type":"preference","tags":["database","migrations"]}
+{"content":"Logging uses structured JSON via pino","type":"decision","tags":["logging","observability"]}
+{"content":"User prefers terse responses without trailing summaries","type":"preference","tags":["communication"]}
+{"content":"WebSocket connections use socket.io with Redis adapter for scaling","type":"decision","tags":["websockets","architecture"]}
+{"content":"File uploads go to S3 with presigned URLs, never through the API server","type":"decision","tags":["files","architecture"]}
+{"content":"Cron jobs are managed by BullMQ with Redis backend","type":"decision","tags":["jobs","architecture"]}

package/hooks/hooks-cursor.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/session-start/run.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/session-start/run.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-end/run.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# total-recall SessionEnd hook
+# Reminder to trigger compaction via MCP tool
+
+echo "total-recall: session ending, compaction will run via session_end tool"

package/hooks/session-start/run.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# total-recall SessionStart hook
+# Injects the core memory skill into the session
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SKILL_FILE="$PLUGIN_ROOT/skills/memory/SKILL.md"
+
+if [ -f "$SKILL_FILE" ]; then
+  cat "$SKILL_FILE"
+fi

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@strvmarv/total-recall",
+  "version": "0.1.0",
+  "description": "Multi-tiered memory and knowledge base plugin for TUI coding assistants",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "total-recall": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "eval/",
+    "src/defaults.toml",
+    ".claude-plugin/",
+    ".copilot-plugin/",
+    ".cursor-plugin/",
+    ".opencode/",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strvmarv/total-recall.git"
+  },
+  "homepage": "https://github.com/strvmarv/total-recall",
+  "bugs": {
+    "url": "https://github.com/strvmarv/total-recall/issues"
+  },
+  "author": "strvmarv",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "memory",
+    "knowledge-base",
+    "claude-code",
+    "copilot-cli",
+    "opencode",
+    "cline",
+    "cursor",
+    "sqlite",
+    "vector-search",
+    "embeddings",
+    "ai-coding",
+    "tui"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.0.0",
+    "onnxruntime-node": "^1.20.0",
+    "sqlite-vec": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/skills/forget/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: forget
+description: Use when user says "/memory forget", "remove that memory", "delete memory about", or asks to remove specific entries from total-recall.
+---
+
+# Memory Deletion
+
+User-controlled deletion with transparency and confirmation.
+
+## Process
+
+1. Call `memory_search` with the user's query to find matching entries
+2. Present matches with: ID, content preview, tier, source, access count
+3. If source is from a host tool import, note that the original file is NOT touched
+4. Ask user which entries to delete (by number or "all")
+5. Call `memory_delete` for each selected entry with a reason
+6. Confirm deletion
+
+## Safety
+
+- Never auto-delete without user confirmation
+- Never modify host tool source files
+- Always log the deletion reason

package/skills/ingest/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ingest
+description: Use when user says "/memory ingest", "add to knowledge base", "ingest these docs", or asks to import files or directories into total-recall.
+---
+
+# Knowledge Base Ingestion
+
+Add files or directories to the knowledge base for semantic retrieval.
+
+## Process
+
+1. Determine if the path is a file or directory
+2. For files: call `kb_ingest_file` with the path
+3. For directories: call `kb_ingest_dir` with the path
+4. Report: collection name, document count, chunk count, validation results
+5. Suggest a test query to verify ingestion worked
+
+## Supported Formats
+
+Markdown, TypeScript, JavaScript, Python, Go, Rust, JSON, YAML, plain text. Code files are split on function/class boundaries. Markdown is split on headings.

package/skills/memory/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: memory
+description: Use at every session start to enable automatic memory capture, retrieval, and context injection. Triggers on SessionStart, detects corrections and preferences during conversation, queries warm tier on user messages, and compacts at session end.
+---
+
+# Automatic Memory Management
+
+## Overview
+
+This skill governs total-recall's always-on memory behavior. It runs silently, capturing corrections, preferences, and decisions into the hot tier, retrieving relevant warm memories per query, and compacting at session end.
+
+## At Session Start
+
+1. Call the `session_start` MCP tool. It will:
+   - Sync any new imports from detected host tools
+   - Assemble the hot tier (carry-forwards + relevant warm memories + pinned knowledge)
+   - Return injectable context
+
+2. Silently incorporate the returned context into your working memory. Do not announce what was loaded unless the user asks.
+
+## During Conversation
+
+### Capture (automatic, silent)
+
+When you detect any of these patterns in the user's message, call `memory_store`:
+
+- **Correction**: User says "no", "not that", "actually", "use X instead" -> store with type "correction"
+- **Preference**: User expresses how they want things done -> store with type "preference"
+- **Decision**: A non-obvious architectural or design choice is made -> store with type "decision"
+
+Do NOT announce that you stored a memory. Do NOT ask permission. Just store it.
+
+### Retrieve (automatic, silent)
+
+On each user message, if the message is a question or task request:
+
+1. Call `memory_search` with the user's message as query, searching warm tier, scoped to the current project
+2. If warm results are insufficient (top score < 0.5), also search cold/knowledge tier
+3. Use retrieved context to inform your response
+4. Do NOT announce what you retrieved unless the user asks "what do you remember about X"
+
+### When User Asks About Memory
+
+If the user asks "what do you know about...", "what do you remember...", or "show me memories about...":
+- Call `memory_search` explicitly with their query
+- Present results transparently with tier, score, and source
+
+## At Session End
+
+Call `session_end` MCP tool. It will:
+- Run hot tier compaction (decay-scored promotion/discard)
+- Log compaction events
+- Update retrieval event outcomes
+
+## Key Rules
+
+- NEVER announce memory operations unless asked
+- ALWAYS store corrections -- they are the highest-value memories
+- ALWAYS search warm tier before answering questions about the project
+- NEVER modify the user's host tool memory files (Claude Code memory/, CLAUDE.md, etc.)

package/skills/search/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: search
+description: Use when user says "/memory search", "search my memory", "what do I know about", "find in knowledge base", or asks to look up something in their stored context.
+---
+
+# Memory Search
+
+Explicit user-initiated search across all tiers and content types.
+
+## Process
+
+1. Call `memory_search` with the user's query, all tiers enabled, top_k=10
+2. Format results grouped by tier, then by content type
+3. Show: content preview (first 100 chars), similarity score, source, tags
+4. Offer actions: "/memory promote <id>" or "/memory forget <id>"
+
+## Output Format
+
+Group results by tier (hot first, then warm, then cold). Show scores rounded to 2 decimal places. Include source attribution for imported entries.

package/skills/status/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: status
+description: Use when user says "/memory status", "/memory eval", "how is memory performing", "show memory dashboard", or asks about total-recall health or metrics.
+---
+
+# Memory Status & Evaluation
+
+Show the TUI dashboard or detailed evaluation metrics.
+
+## For /memory status
+
+Call the `status` MCP tool and format the response as a dashboard showing:
+- Tier sizes (hot/warm/cold with counts)
+- Knowledge base stats (collections, documents, chunks)
+- DB size and embedding model info
+- Session activity summary
+
+## For /memory eval
+
+Call `eval_report` for live metrics. Show:
+- Precision@3, hit rate, miss rate, MRR (7-day rolling)
+- Breakdown by tier and content type
+- Top misses and false positives
+- Compaction health
+
+## For /memory eval --benchmark
+
+Call `eval_benchmark`. Show synthetic benchmark results with pass/fail thresholds.
+
+## For /memory eval --compare <name>
+
+Call `eval_report` with the named config snapshot for comparison. Show side-by-side metrics with deltas and trend arrows.

package/src/defaults.toml

@@ -0,0 +1,28 @@
+# total-recall default configuration
+# Copy to ~/.total-recall/config.toml to override
+
+[tiers.hot]
+max_entries = 50
+token_budget = 4000
+carry_forward_threshold = 0.7
+
+[tiers.warm]
+max_entries = 10000
+retrieval_top_k = 5
+similarity_threshold = 0.65
+cold_decay_days = 30
+
+[tiers.cold]
+chunk_max_tokens = 512
+chunk_overlap_tokens = 50
+lazy_summary_threshold = 5
+
+[compaction]
+decay_half_life_hours = 168
+warm_threshold = 0.3
+promote_threshold = 0.7
+warm_sweep_interval_days = 7
+
+[embedding]
+model = "all-MiniLM-L6-v2"
+dimensions = 384