causantic 0.4.0 → 0.4.2

package/README.md

@@ -8,7 +8,7 @@
 
 **Long-term memory for Claude Code — local-first, graph-augmented, self-benchmarking.**
 
-No cloud. No API keys. No data leaves your machine. Runs entirely on your hardware with optional per-chunk encryption.
+No cloud. No data leaves your machine. Runs entirely on your hardware with optional per-chunk encryption. An optional Anthropic API key enables cluster topic labeling via Haiku — all core retrieval works without it.
 
 <p align="center">
 <strong>Long-term episodic memory for Claude Code</strong><br/>
@@ -74,7 +74,7 @@ Vector search finds chunks that *look similar*. BM25 keyword search finds chunks
 **3. Sequential Causal Graph with Episodic Chain Walking**
 Chunks are connected in a sequential linked list — intra-turn chunks chained sequentially, inter-turn edges linking last→first, cross-session edges bridging sessions. The `recall` tool walks this graph backward to reconstruct episodic narratives; `predict` walks forward. Chains are scored by cosine similarity per token, producing ordered narratives where each chunk adds new information.
 
-**5. HDBSCAN Cluster-Guided Expansion**
+**4. HDBSCAN Cluster-Guided Expansion**
 Topic clusters group semantically related chunks. During retrieval, results expand through cluster siblings — surfacing context that neither vector nor keyword search found independently. Native TypeScript implementation (130× faster than hdbscan-ts).
 
 **5. Self-Benchmarking Suite**
@@ -192,18 +192,18 @@ Causantic installs 14 Claude Code slash commands (via `npx causantic init`) for
 
 | Skill | Description |
 |-------|-------------|
-| `/causantic-recall [query]` | Walk causal chains to reconstruct narrative (how did we solve X?) |
-| `/causantic-search [query]` | Ranked discovery across memory by relevance (what do I know about X?) |
-| `/causantic-predict <context>` | Surface relevant past context proactively for a given task |
-| `/causantic-explain [question]` | Answer "why" questions and explore codebase areas |
+| `/causantic-recall [query]` | Reconstruct how something happened — walks backward through causal chains (how did we solve X?) |
+| `/causantic-search [query]` | Broad discovery — find everything memory knows about a topic (what do I know about X?) |
+| `/causantic-predict <context>` | Surface what came after similar past situations — walks forward through causal chains (what's likely relevant next?) |
+| `/causantic-explain [question]` | Answer "why" questions using memory + codebase (why does X work this way?) |
 | `/causantic-debug [error]` | Search for prior encounters with an error (auto-extracts from conversation if no argument) |
 | `/causantic-resume` | Resume interrupted work — start-of-session briefing |
-| `/causantic-reconstruct [time]` | Reconstruct session context by time range |
-| `/causantic-summary [time]` | Summarize recent work across sessions |
+| `/causantic-reconstruct [time]` | Replay a past session chronologically by time range |
+| `/causantic-summary [time]` | Factual recap of what was done across recent sessions |
 | `/causantic-list-projects` | Discover available projects in memory |
 | `/causantic-status` | Check system health and memory statistics |
 | `/causantic-crossref [pattern]` | Search across all projects for reusable patterns |
-| `/causantic-retro [scope]` | Retrospective analysis across past sessions |
+| `/causantic-retro [scope]` | Surface recurring patterns, problems, and decisions across sessions |
 | `/causantic-cleanup` | Memory-informed codebase review and cleanup plan |
 | `/causantic-forget [query]` | Delete memory by topic, time range, or session (always previews first) |
 

package/dist/cli/skill-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-templates.d.ts","sourceRoot":"","sources":["../../src/cli/skill-templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,EAAE,aAAa,EA8xC3C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAqEhD"}
+{"version":3,"file":"skill-templates.d.ts","sourceRoot":"","sources":["../../src/cli/skill-templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,EAAE,aAAa,EA8xC3C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CA8FhD"}

package/dist/cli/skill-templates.js

@@ -1330,24 +1330,24 @@ Long-term memory is available via the \`causantic\` MCP server.
 ### Skills
 
 **Core retrieval:**
-- \`/causantic-recall [query]\` — Walk causal chains to reconstruct narrative (how did we solve X?)
-- \`/causantic-search [query]\` — Ranked discovery across memory by relevance (what do I know about X?)
-- \`/causantic-predict <context>\` — Surface relevant past context proactively for a given task
+- \`/causantic-recall [query]\` — Reconstruct how something happened — walks backward through causal chains (how did we solve X?)
+- \`/causantic-search [query]\` — Broad discovery — find everything memory knows about a topic (what do I know about X?)
+- \`/causantic-predict <context>\` — Surface what came after similar past situations — walks forward through causal chains (what's likely relevant next?)
 
 **Understanding & analysis:**
-- \`/causantic-explain [question]\` — Answer "why" questions and explore codebase areas
+- \`/causantic-explain [question]\` — Answer "why" questions using memory + codebase (why does X work this way?)
 - \`/causantic-debug [error]\` — Search for prior encounters with an error (auto-extracts from conversation if no argument)
 
 **Session & project navigation:**
-- \`/causantic-resume\` — Resume interrupted work (start-of-session briefing)
-- \`/causantic-reconstruct [time range]\` — Reconstruct session context by time
-- \`/causantic-summary [time range]\` — Summarize recent work across sessions
+- \`/causantic-resume\` — Resume interrupted work — start-of-session briefing
+- \`/causantic-reconstruct [time range]\` — Replay a past session chronologically by time range
+- \`/causantic-summary [time range]\` — Factual recap of what was done across recent sessions
 - \`/causantic-list-projects\` — Discover available projects
 - \`/causantic-status\` — Check system health and memory statistics
 
 **Cross-cutting analysis:**
 - \`/causantic-crossref [pattern]\` — Search across all projects for reusable patterns
-- \`/causantic-retro [scope]\` — Retrospective pattern analysis across sessions
+- \`/causantic-retro [scope]\` — Surface recurring patterns, problems, and decisions across sessions
 - \`/causantic-cleanup\` — Memory-informed codebase review and cleanup plan
 
 **Memory management:**
@@ -1380,6 +1380,31 @@ Long-term memory is available via the \`causantic\` MCP server.
 - The user explicitly provides all needed context
 - First attempt at resolving a new error (try solving it first, check memory if stuck)
 
+### CLI Commands
+
+When the user asks to run Causantic operations from the command line:
+
+\`\`\`
+npx causantic init                  — Setup wizard (MCP, hooks, skills, import)
+npx causantic serve                 — Start the MCP server
+npx causantic dashboard             — Launch the web dashboard
+npx causantic batch-ingest [dir]    — Ingest all sessions from a directory
+npx causantic ingest <path>         — Ingest a single session or project
+npx causantic recall <query>        — Query memory from the CLI
+npx causantic stats                 — Show memory statistics
+npx causantic health                — Check system health
+npx causantic config [subcommand]   — Manage configuration
+npx causantic maintenance [status|run|daemon] — Maintenance tasks
+npx causantic benchmark-collection [--quick|--standard|--full] — Run benchmarks
+npx causantic encryption [subcommand] — Manage database encryption
+npx causantic export                — Export memory data
+npx causantic import <file>         — Import memory data
+npx causantic hook <name>           — Run a hook manually
+npx causantic uninstall             — Remove Causantic and all its artifacts
+\`\`\`
+
+Run \`npx causantic <command> --help\` for command-specific options.
+
 ### Combining Memory with Other Tools
 
 Memory provides historical context, not current code state. After retrieving memory:

package/dist/cli/skill-templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-templates.js","sourceRoot":"","sources":["../../src/cli/skill-templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCZ;KACE;IACD;QACE,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCZ;KACE;IACD;QACE,OAAO,EAAE,mBAAmB;QAC5B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCZ;KACE;IACD;QACE,OAAO,EAAE,mBAAmB;QAC5B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEZ;KACE;IACD;QACE,OAAO,EAAE,iBAAiB;QAC1B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDZ;KACE;IACD;QACE,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDZ;KACE;IACD;QACE,OAAO,EAAE,uBAAuB;QAChC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DZ;KACE;IACD;QACE,OAAO,EAAE,yBAAyB;QAClC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BZ;KACE;IACD;QACE,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCZ;KACE;IACD;QACE,OAAO,EAAE,mBAAmB;QAC5B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDZ;KACE;IACD;QACE,OAAO,EAAE,oBAAoB;QAC7B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDZ;KACE;IACD;QACE,OAAO,EAAE,iBAAiB;QAC1B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCZ;KACE;IACD;QACE,OAAO,EAAE,mBAAmB;QAC5B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAumBZ;KACE;IACD;QACE,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqFZ;KACE;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,eAAe,GAAG,iCAAiC,CAAC;IAC1D,MAAM,aAAa,GAAG,+BAA+B,CAAC;IAEtD,OAAO,GAAG,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgEzB,aAAa,EAAE,CAAC;AAClB,CAAC"}
+{"version":3,"file":"skill-templates.js","sourceRoot":"","sources":["../../src/cli/skill-templates.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "causantic",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Long-term memory for Claude Code — local-first, graph-augmented, self-benchmarking",
   "type": "module",
   "private": false,