causantic 0.2.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024-2026 Entrolution
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,332 @@
+# Causantic
+
+[![npm version](https://img.shields.io/npm/v/causantic)](https://www.npmjs.com/package/causantic)
+[![CI](https://github.com/Entrolution/causantic/actions/workflows/ci.yml/badge.svg)](https://github.com/Entrolution/causantic/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)](https://www.typescriptlang.org/)
+
+**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.
+
+<p align="center">
+<strong>4.65× the relevant context</strong> vs semantic embedding alone<br/>
+<sub>Median 4.54× across 492 queries · Range 3.60× – 5.87×</sub>
+</p>
+
+## Quick Start
+
+```bash
+# Install
+npm install causantic
+
+# Initialize (creates dirs, configures MCP, offers to import sessions)
+npx causantic init
+
+# Query memory
+npx causantic recall "authentication flow"
+
+# Launch the dashboard
+npx causantic dashboard
+```
+
+## Who Is This For?
+
+Developers using Claude Code who want their AI assistant to **remember across sessions**. When you switch projects, return after a weekend, or need context from three sessions ago, Causantic retrieves the right history automatically.
+
+## Why Causantic?
+
+Most AI memory systems use vector embeddings for similarity search. Causantic does too — but adds a **causal graph** that tracks *relationships* between memory chunks, **BM25 keyword search** for exact matches, and **HDBSCAN clustering** for topic expansion. The result:
+
+| | Vector Search Only | Causantic |
+|---|---|---|
+| **Finds similar content** | Yes | Yes |
+| **Finds lexically relevant content** | No | Yes (BM25 keyword search) |
+| **Finds related context** | No | Yes (causal edges) |
+| **Finds topically related context** | No | Yes (cluster expansion) |
+| **Temporal awareness** | Wall-clock decay | Logical hop decay |
+| **Context retrieval** | 1× | **4.65×** |
+| **Handles project switches** | Breaks continuity | Preserves causality |
+| **Bidirectional queries** | Forward only | Backward + Forward |
+
+### How It Compares
+
+| System | Local-First | Temporal Decay | Graph Structure | Self-Benchmarking | Hop-Based Distance |
+|--------|:-----------:|:--------------:|:--------------:|:-----------------:|:------------------:|
+| **Causantic** | **Yes** | **Hop-based** | **9-type causal** | **Yes** | **Yes** |
+| Mem0 | No (Cloud) | None | Paid add-on | No | No |
+| Cognee | Self-hostable | None | Triplet extraction | No | No |
+| Letta/MemGPT | Self-hostable | Summarization | None | No | No |
+| Zep | Enterprise | Bi-temporal | Temporal KG | No | No |
+| GraphRAG | Self-hostable | Static corpus | Hierarchical | No | No |
+
+See [Landscape Analysis](docs/research/approach/landscape-analysis.md) for detailed per-system analysis.
+
+## Key Differentiators
+
+**1. Local-First with Encryption**
+All data stays on your machine. Optional per-chunk encryption (ChaCha20-Poly1305) with keys stored in your system keychain. No cloud dependency.
+
+**2. Hybrid BM25 + Vector Search**
+Vector search finds chunks that *look similar*. BM25 keyword search finds chunks with *exact lexical matches* — function names, error codes, CLI flags. Both run in parallel and fuse via Reciprocal Rank Fusion (RRF).
+
+**3. Causal Graphs with 9 Evidence-Weighted Edge Types**
+Chunks are connected by file-path references, code entities, explicit backreferences, error fragments, topic continuity, and more. Each edge type has an empirically determined weight. The graph finds chunks that are *causally related* — not just similar.
+
+**4. Hop-Based Decay with Direction-Specific Curves**
+Returning to a project after a weekend shouldn't make yesterday's work seem "old." Distance is measured in logical D-T-D hops, not elapsed time. Backward edges (dies@10 hops, 1.35× MRR vs exponential) and forward edges (5-hop hold, dies@20, 3.71× MRR) use different decay profiles.
+
+**5. 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).
+
+**6. Self-Benchmarking Suite**
+Measure how well your memory system is working with built-in benchmarks. Health, retrieval quality, graph value, and latency — scored and tracked over time with specific tuning recommendations.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Claude Code Session                          │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Hook System                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │session-start │  │ pre-compact  │  │ claudemd-generator   │   │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Ingestion Pipeline                            │
+│  ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐   │
+│  │  Parser  │→ │ Chunker  │→ │ Embedder   │→ │ Edge Creator │   │
+│  └──────────┘  └──────────┘  └────────────┘  └──────────────┘   │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       Storage Layer                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │   SQLite     │  │   LanceDB    │  │   Vector Clocks      │   │
+│  │ (chunks,     │  │ (embeddings) │  │   (logical time)     │   │
+│  │  edges, FTS5)│  │              │  │                      │   │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Retrieval System                              │
+│  ┌──────────┐ ┌──────────┐                                      │
+│  │ Vector   │ │ Keyword  │  (parallel)                          │
+│  │ Search   │ │ (BM25)   │                                      │
+│  └────┬─────┘ └────┬─────┘                                      │
+│       └──────┬──────┘                                            │
+│              ▼                                                   │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │  RRF Fusion  │→ │ Cluster      │→ │ Graph Traversal      │   │
+│  │              │  │ Expansion    │  │ + Context Assembly    │   │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       MCP Server                                 │
+│  ┌────────┐ ┌────────┐ ┌─────────┐ ┌───────────┐ ┌───────────┐ │
+│  │ recall │ │explain │ │ predict │ │list-      │ │list-      │ │
+│  │        │ │        │ │         │ │projects   │ │sessions   │ │
+│  └────────┘ └────────┘ └─────────┘ └───────────┘ └───────────┘ │
+│  ┌─────────────┐                                                │
+│  │ reconstruct │                                                │
+│  └─────────────┘                                                │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Web Dashboard                                │
+│  ┌──────────┐ ┌────────┐ ┌───────────┐ ┌──────────┐ ┌────────┐ │
+│  │ Overview │ │ Search │ │ Graph     │ │ Clusters │ │Projects│ │
+│  │          │ │        │ │ Explorer  │ │          │ │        │ │
+│  └──────────┘ └────────┘ └───────────┘ └──────────┘ └────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## MCP Tools
+
+The MCP server exposes six tools:
+
+| Tool | Description |
+|------|-------------|
+| `recall` | Semantic search with graph-augmented retrieval. Supports `range` (short/long) and `project` filtering. |
+| `explain` | Long-range historical context for complex questions. Default: long-range retrieval. |
+| `predict` | Proactive suggestions based on current context. |
+| `list-projects` | Discover available projects with chunk counts and date ranges. |
+| `list-sessions` | Browse sessions for a project with time filtering. |
+| `reconstruct` | Rebuild session context chronologically — "what did I work on yesterday?" |
+
+### Claude Code Integration
+
+Add to your Claude Code MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["causantic", "serve"]
+    }
+  }
+}
+```
+
+Or run `npx causantic init` to configure automatically.
+
+## Skills
+
+Causantic installs 11 Claude Code slash commands (via `npx causantic init`) for natural-language interaction with memory:
+
+| Skill | Description |
+|-------|-------------|
+| `/causantic-recall [query]` | Look up context from past sessions |
+| `/causantic-explain [topic]` | Understand history behind decisions |
+| `/causantic-predict` | Surface relevant past context proactively |
+| `/causantic-resume` | Resume interrupted work — start-of-session briefing |
+| `/causantic-debug [error]` | Search for prior encounters with an error (auto-extracts from conversation if no argument) |
+| `/causantic-context [area]` | Deep dive into a codebase area's history and decisions |
+| `/causantic-crossref [pattern]` | Search across all projects for reusable patterns |
+| `/causantic-retro [scope]` | Retrospective analysis across past sessions |
+| `/causantic-cleanup` | Memory-informed codebase review and cleanup plan |
+| `/causantic-list-projects` | Discover available projects in memory |
+| `/causantic-reconstruct [time]` | Reconstruct session context by time range |
+
+Skills are installed to `~/.claude/skills/causantic-*/` and work as slash commands in Claude Code. They orchestrate the MCP tools above with structured prompts tailored to each use case.
+
+## Dashboard
+
+Explore your memory visually:
+
+```bash
+npx causantic dashboard
+```
+
+Opens at [http://localhost:3333](http://localhost:3333) with 5 pages: Overview (collection stats), Search (query memory), Graph Explorer (D3.js visualization), Clusters (topic browser), and Projects (per-project breakdowns).
+
+See [Dashboard Guide](docs/guides/dashboard.md).
+
+## Benchmarking
+
+Measure how well your memory system is working:
+
+```bash
+# Quick health check (~1 second)
+npx causantic benchmark-collection --quick
+
+# Standard benchmark (~30 seconds)
+npx causantic benchmark-collection
+
+# Full benchmark with graph value and latency (~2-5 minutes)
+npx causantic benchmark-collection --full
+```
+
+Scores health (20%), retrieval quality (35%), graph value (30%), and latency (15%) — with specific tuning recommendations. Track improvements over time with `--history`.
+
+See [Benchmarking Guide](docs/guides/benchmarking.md).
+
+## Configuration
+
+Create `causantic.config.json` in your project root:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/Entrolution/causantic/main/config.schema.json",
+  "decay": {
+    "backward": {
+      "type": "linear",
+      "diesAtHops": 10
+    },
+    "forward": {
+      "type": "delayed-linear",
+      "holdHops": 5,
+      "diesAtHops": 20
+    }
+  },
+  "clustering": {
+    "threshold": 0.10,
+    "minClusterSize": 4
+  }
+}
+```
+
+See [Configuration Reference](docs/reference/configuration.md) for all options.
+
+## Security
+
+- **Per-chunk encryption**: ChaCha20-Poly1305 with keys stored in your system keychain
+- **Local-only storage**: SQLite + LanceDB on your filesystem, no cloud sync
+- **Embedding vector protection**: Encrypted vectors prevent semantic reconstruction
+
+See [Security Guide](docs/guides/security.md).
+
+## Documentation
+
+- [Getting Started](docs/getting-started/installation.md) — Installation and setup
+- [User Guides](docs/guides/) — Dashboard, benchmarking, integration, security, maintenance
+- [CLI Reference](docs/reference/cli-commands.md) — All commands and options
+- [MCP Tools Reference](docs/reference/mcp-tools.md) — Tool schemas and usage
+- [Configuration Reference](docs/reference/configuration.md) — All configuration options
+- [Research Documentation](docs/research/) — Experiment results and design decisions
+- [Design Decision Log](docs/research/decisions.md) — Why things are the way they are
+
+## Research
+
+Built on rigorous experimentation across 75 sessions and 492 queries:
+
+| Experiment | Result | Comparison |
+|------------|--------|------------|
+| Graph Traversal | **4.65×** context | vs vector-only |
+| Forward Decay | **3.71×** MRR | vs time-based decay |
+| Backward Decay | **1.35×** MRR | vs time-based decay |
+| Topic Detection | 0.998 AUC | near-perfect accuracy |
+| Clustering | F1=0.940 | 100% precision |
+| Thinking Block Removal | +0.063 AUC | embedding quality improvement |
+
+See [Research Documentation](docs/research/) for detailed findings, and the [Design Decision Log](docs/research/decisions.md) for the story of how each decision was made.
+
+### The Role of Entropy
+
+The name reflects how **discrimination degrades along causal paths** — the same way information diffuses with each causal jump.
+
+Chunks close to your query point are sharply ranked: the graph can clearly distinguish what's most relevant. But as traversal moves outward, edge weights multiply — and since each weight is < 1, the products converge toward zero. You progressively lose the ability to discriminate between distant nodes. This is entropy flowing along causal lines.
+
+This isn't a limitation — it's the design. The loss of discriminating power:
+
+- **Prevents unbounded graph growth**: distant, low-discrimination regions naturally fade rather than accumulating indefinitely
+- **Keeps memory current**: the graph evolves with your usage of Claude — recent causal paths retain sharp discrimination while older paths gracefully compress
+- **Mirrors how relevance actually works**: the further a piece of context is from your current work (in causal hops, not wall-clock time), the less precisely it needs to be ranked
+
+The result is **natural causal compression** — a graph that stays focused on what matters without manual pruning or arbitrary cutoffs.
+
+See [The Role of Entropy](docs/research/approach/role-of-entropy.md) for the full explanation.
+
+## Maintenance
+
+```bash
+# Run specific maintenance task
+npx causantic maintenance run prune-graph
+
+# Check maintenance status
+npx causantic maintenance status
+
+# Run as background daemon
+npx causantic maintenance daemon
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting PRs.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

package/config.schema.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Entrolution/causantic/main/config.schema.json",
+  "title": "Causantic Configuration",
+  "description": "Configuration schema for Causantic",
+  "type": "object",
+  "properties": {
+    "decay": {
+      "type": "object",
+      "description": "Temporal decay settings for graph edges",
+      "properties": {
+        "backward": {
+          "type": "object",
+          "description": "Decay for backward (historical) edges",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["linear", "exponential", "delayed-linear"],
+              "default": "linear",
+              "description": "Decay curve type"
+            },
+            "diesAtHops": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 10,
+              "description": "Number of hops at which weight reaches zero"
+            },
+            "holdHops": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 50,
+              "default": 0,
+              "description": "Number of hops to hold at full weight (for delayed types)"
+            }
+          },
+          "additionalProperties": false
+        },
+        "forward": {
+          "type": "object",
+          "description": "Decay for forward (predictive) edges",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["linear", "exponential", "delayed-linear"],
+              "default": "delayed-linear",
+              "description": "Decay curve type"
+            },
+            "diesAtHops": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 20,
+              "description": "Number of hops at which weight reaches zero"
+            },
+            "holdHops": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 50,
+              "default": 5,
+              "description": "Number of hops to hold at full weight (for delayed types)"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "clustering": {
+      "type": "object",
+      "description": "HDBSCAN clustering settings",
+      "properties": {
+        "threshold": {
+          "type": "number",
+          "minimum": 0.01,
+          "maximum": 0.5,
+          "default": 0.10,
+          "description": "Angular distance threshold for cluster assignment"
+        },
+        "minClusterSize": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 100,
+          "default": 4,
+          "description": "Minimum points required to form a cluster"
+        }
+      },
+      "additionalProperties": false
+    },
+    "traversal": {
+      "type": "object",
+      "description": "Graph traversal settings",
+      "properties": {
+        "maxDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50,
+          "default": 15,
+          "description": "Maximum traversal depth from seed nodes"
+        },
+        "minWeight": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.01,
+          "description": "Minimum edge weight to continue traversal"
+        },
+        "directHitBoost": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 1.5,
+          "description": "Score multiplier for direct search hits (vector/keyword/cluster)"
+        },
+        "graphAgreementBoost": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 2.0,
+          "description": "Score boost multiplier when a chunk is found by both vector search and graph traversal"
+        }
+      },
+      "additionalProperties": false
+    },
+    "tokens": {
+      "type": "object",
+      "description": "Token budget settings",
+      "properties": {
+        "claudeMdBudget": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 10000,
+          "default": 500,
+          "description": "Token budget for CLAUDE.md memory section"
+        },
+        "mcpMaxResponse": {
+          "type": "integer",
+          "minimum": 500,
+          "maximum": 50000,
+          "default": 2000,
+          "description": "Maximum tokens for MCP tool responses"
+        }
+      },
+      "additionalProperties": false
+    },
+    "storage": {
+      "type": "object",
+      "description": "Storage paths",
+      "properties": {
+        "dbPath": {
+          "type": "string",
+          "default": "~/.causantic/memory.db",
+          "description": "Path to SQLite database file (~ expands to home)"
+        },
+        "vectorPath": {
+          "type": "string",
+          "default": "~/.causantic/vectors",
+          "description": "Path to LanceDB vector store directory"
+        }
+      },
+      "additionalProperties": false
+    },
+    "llm": {
+      "type": "object",
+      "description": "LLM settings for optional features",
+      "properties": {
+        "clusterRefreshModel": {
+          "type": "string",
+          "default": "claude-3-haiku-20240307",
+          "description": "Model to use for cluster description refresh"
+        },
+        "refreshRateLimitPerMin": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 30,
+          "description": "Rate limit for LLM refresh calls per minute"
+        }
+      },
+      "additionalProperties": false
+    },
+    "encryption": {
+      "type": "object",
+      "description": "Database encryption settings",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable database encryption at rest"
+        },
+        "cipher": {
+          "type": "string",
+          "enum": ["chacha20", "sqlcipher"],
+          "default": "chacha20",
+          "description": "Encryption cipher (chacha20 is 2-3x faster on ARM)"
+        },
+        "keySource": {
+          "type": "string",
+          "enum": ["keychain", "env", "prompt"],
+          "default": "keychain",
+          "description": "Where to get encryption key: keychain (OS secret store), env (CAUSANTIC_DB_KEY), prompt (CLI only)"
+        },
+        "auditLog": {
+          "type": "boolean",
+          "default": false,
+          "description": "Log database access attempts to ~/.causantic/audit.log"
+        }
+      },
+      "additionalProperties": false
+    },
+    "vectors": {
+      "type": "object",
+      "description": "Vector storage settings",
+      "properties": {
+        "ttlDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "default": 90,
+          "description": "TTL in days for vectors. Vectors accessed within this period are kept."
+        }
+      },
+      "additionalProperties": false
+    },
+    "embedding": {
+      "type": "object",
+      "description": "Embedding inference settings",
+      "properties": {
+        "device": {
+          "type": "string",
+          "enum": ["auto", "coreml", "cuda", "cpu", "wasm"],
+          "default": "auto",
+          "description": "Device for embedding inference. 'auto' detects hardware capabilities."
+        }
+      },
+      "additionalProperties": false
+    },
+    "maintenance": {
+      "type": "object",
+      "description": "Maintenance schedule settings",
+      "properties": {
+        "clusterHour": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 23,
+          "default": 2,
+          "description": "Hour of day (0-23) to run reclustering. Prune and cleanup run 1h and 1.5h after."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/dist/cli/commands/archive.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../types.js';
+export declare const exportCommand: Command;
+export declare const importCommand: Command;
+//# sourceMappingURL=archive.d.ts.map

package/dist/cli/commands/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,eAAO,MAAM,aAAa,EAAE,OAuC3B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,OAsC3B,CAAC"}