autoctxd 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-05-15
+
+Quality pass before the first public release. Same surface area, three pre-existing bugs in the classifier and decision extractor fixed.
+
+### Fixed
+- Decision extractor no longer captures `npm install` / `bun add` / `pip install` mentions in Monitor commands, task descriptions, and log streams as architectural decisions. The dependency detector now validates the captured token against a reject list (`output`, `progress`, `tsx`, `tests`, `dev`, `prod`, …) and rejects numeric-only tokens, very short bare words, and anything without alphabetic characters.
+- Classifier filters internal harness tools (`Monitor`, `ToolSearch`, `TaskStop`, `TaskOutput`, `TodoWrite`) and Bash/PowerShell summaries that carry their payloads. These are still persisted but at importance 1, so they fall out of "top observations" and never get injected as recovered context.
+- Bash/PowerShell exploration commands (`List …`, `Check …`, `Find …`, `git status`, `git log`, `git diff`, `git blame`, …) are now classified as `research` with low importance instead of dropping to `other`. PowerShell gets the same Bash heuristics it lacked before.
+- Decisions no longer duplicate across sessions. A unique index on `(project_path, title)` plus `INSERT OR IGNORE` makes re-extraction idempotent.
+- The decision extractor's "tool-prefixed noise" guard was extended to catch `Bash:` / `PowerShell:` / `Edit:` / `Edited ` / `Monitor:` / `ToolSearch:` / `TodoWrite` / `TaskStop:` / `TaskOutput:` summaries that previously slipped through when the classifier promoted them to type=decision via a stray keyword.
+
+### Added
+- `autoctxd cleanup-decisions [--dry-run]` — deletes generic-word noise (`Added npm dep: output`, …) and tool-prefixed leftovers from the pre-0.4 extractor, and collapses any cross-session duplicates that predate the unique index. Idempotent; safe to re-run.
+- Schema migration: cross-session duplicate decisions in legacy DBs are collapsed to the earliest row on open, then the unique index is enforced going forward.
+
+### Improved
+- On the author's real DB, this collapsed the architectural-decisions feed from 142 noisy rows to 4 actual decisions.
+
+## [0.3.0] - 2026-05-15
+
+First public release.
+
+### Added
+- **MCP server** with 7 tools (`recall_decisions`, `recall_unfinished`, `search_memory`, `get_project_history`, `check_intent`, `record_feedback`, `record_decision`) for active memory recall in Claude Code, Cursor, Windsurf, Cline, and Claude Desktop.
+- **Active Guard** — `check_intent` flags actions that contradict past decisions before they happen.
+- **Feedback loop** — `record_feedback` lets the system learn which memories are useful, irrelevant, or wrong per user.
+- **Pluggable embeddings** — TF-IDF (default, zero-install), MiniLM-L6-v2 via `@xenova/transformers` (opt-in), and Ollama for any local embedding model. Switch with `autoctxd embeddings switch`; cache is partitioned per provider.
+- **Local web dashboard** at `http://localhost:4589` — metric cards, activity timeline, decision feed, decision chains, pattern panel, hybrid search.
+- **Decision chains** — automatically detects sequences like `mysql → postgres → sqlite` across sessions.
+- **Token-savings metrics** — accumulated estimate of tokens injected vs. tokens that would otherwise be re-explained.
+- **One-command installer** for macOS, Linux (`install.sh`) and Windows (`install.ps1`) — bootstraps Bun if missing, clones the repo, installs deps, initializes the DB, registers the hooks in `settings.json` (non-destructive merge).
+- **Health-check doctor** (`autoctxd doctor`) — validates runtime, deps, DB schema, LanceDB, hook registration, data directory, and accumulated metrics.
+- **`.autoctxd-ignore`** — gitignore-style opt-out for sensitive projects (single `*` opts the whole project out).
+- **Cross-session pattern detection** — tool preferences, work-type focus, file hotspots, TDD vs. fix-first, peak coding hours (after 3+ sessions per project).
+- **Hybrid search** — semantic (vector) + full-text (FTS5) with project filter.
+- **Re-classification** — `autoctxd reclassify` re-runs the classifier on old observations after improvements.
+- **Export** — `autoctxd export ./my-app > context.md` for project memory as markdown.
+
+### Stack
+- Bun runtime
+- SQLite + FTS5 for structured storage and full-text search
+- LanceDB for vector storage (dim adapts to active provider)
+- Keyword + tool/file heuristics for classification (no LLM calls)
+
+### Privacy
+- No telemetry. No cloud. No network calls during operation.
+- Everything in `~/.claude/autoctxd/data/` — delete to wipe.
+- See [SECURITY.md](SECURITY.md) for the full threat model.
+
+### Testing
+- 75 tests, isolated temp DB (never touches real memory).
+- Cross-provider embeddings benchmark (`bun run benchmark:embeddings`).
+- Tests cover classifier, compressor, decision extractor, decision chains, ignore matcher, embedding providers, and end-to-end integration.
+
+[0.3.0]: https://github.com/autoctxd/autoctxd/releases/tag/v0.3.0

package/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to autoctxd
+
+Thanks for the interest. This is a small, opinionated project — keep PRs focused and the scope tight.
+
+## Dev setup
+
+Requires [Bun](https://bun.sh) ≥ 1.1 and Git.
+
+```bash
+git clone https://github.com/autoctxd/autoctxd.git
+cd autoctxd
+bun install
+bun run src/cli/index.ts init   # creates an isolated DB at ./data/autoctxd.db
+bun test
+```
+
+The test suite uses an isolated temp DB — it never touches your real `~/.claude/autoctxd/data/`.
+
+## Running the hooks against a real Claude Code session
+
+1. Install hooks pointing at your dev clone:
+   ```bash
+   AUTOCTXD_REPO_DIR="$(pwd)" bun run scripts/install-hooks.ts
+   ```
+2. Set `AUTOCTXD_DEBUG=1` so every hook invocation appends to `data/debug.log`.
+3. Start a Claude Code session in any project. `tail -f data/debug.log` while you work.
+4. To uninstall: `bun run scripts/uninstall-hooks.ts`.
+
+## Running the MCP server standalone
+
+```bash
+bun run src/mcp/server.ts
+```
+
+It speaks stdio MCP. Easiest way to poke it is to wire it into Claude Desktop / Cursor / Cline (see `docs/INTEGRATIONS.md`) and call the tools from there.
+
+## Project layout
+
+```
+src/
+  hooks/           pre-tool-use, post-tool-use, stop — the passive capture path
+  mcp/server.ts    7 MCP tools — the active query path
+  ai/              classifier, compressor, decision extractor, active-guard, patterns
+  context/         builder + ranker + formatter for the injected context block
+  db/sqlite/       schema, observations, sessions, decisions, summaries, feedback
+  db/vector/       LanceDB client, embeddings (128-dim TF-IDF hashing), search
+  cli/index.ts     all CLI commands
+  util/            path normalization, debug logger, metrics, ignore matcher
+scripts/           install / uninstall, demo seeders, observation cleanup
+tests/             bun test — classifier, compressor, decisions, integration, ignore
+docs/              INTEGRATIONS.md + assets
+```
+
+## What kind of PRs are welcome
+
+- Bug fixes (with a regression test).
+- Better classification / heuristics. Add a test case in `tests/classifier.test.ts` showing the before/after.
+- New CLI commands that surface data already in the DB.
+- Editor integrations beyond the five already documented.
+- Performance improvements with a measurement, not a guess.
+
+## What is out of scope (for now)
+
+- Cloud sync, accounts, or any network call during operation. The "100% local, zero API" promise is the product.
+- Swapping SQLite or LanceDB for something else.
+- Heavyweight ML dependencies. The MiniLM upgrade on the roadmap is intentionally bounded to `transformers.js` running locally.
+
+If you're not sure whether something is in scope, open an issue first and we'll talk before you write code.
+
+## PR checklist
+
+- [ ] `bun test` passes
+- [ ] `bunx tsc --noEmit` is clean
+- [ ] New behavior has a test
+- [ ] Public API changes are reflected in the README
+- [ ] Commits are scoped and have meaningful messages
+
+## License
+
+By contributing, you agree your contributions will be licensed under the MIT License (see `LICENSE`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eliel Jatib
+
+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,301 @@
+# autoctxd
+
+**Persistent, local memory for Claude Code.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun%20%E2%89%A51.1-black)](https://bun.sh)
+[![CI](https://github.com/autoctxd/autoctxd/actions/workflows/ci.yml/badge.svg)](https://github.com/autoctxd/autoctxd/actions/workflows/ci.yml)
+[![Zero API](https://img.shields.io/badge/API%20calls-0-success)](#privacy)
+[![MCP](https://img.shields.io/badge/MCP-7%20tools-purple)](#how-it-works)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-orange)](CONTRIBUTING.md)
+
+![Active Guard Demo](docs/assets/active-guard-demo.gif)
+
+Every Claude Code session starts from scratch. You re-explain your project, re-state decisions you already made, re-describe what you were in the middle of. `autoctxd` fixes that — silently, locally, with zero API cost.
+
+- **100% local, zero API cost** — pure heuristics, no LLM calls, nothing leaves your machine
+- Captures every tool use automatically through Claude Code hooks
+- Injects the right ~600 tokens of context into each new session
+- Tracks architectural decisions separately — they never get forgotten
+- Detects work patterns across sessions
+- **Active Guard** — flags actions that contradict past decisions, before you make them
+
+## Why autoctxd?
+
+| | autoctxd | Mem0 / memori (cloud) | Plain CLAUDE.md |
+|---|---|---|---|
+| Where your code context lives | **Your disk** | Their servers | A static file you maintain |
+| Cost per session | **$0** | API calls billed | $0 |
+| Captures automatically | **Yes** (hooks) | Via SDK calls | No — you write it |
+| Active recall during reasoning | **Yes** (7 MCP tools) | Yes | No |
+| Flags decision contradictions | **Yes** (Active Guard) | No | No |
+| Works offline | **Yes** | No | Yes |
+| Cross-session patterns / hotspots | **Yes** | Limited | No |
+| Setup | **One command** | Account + API key | Edit a file |
+
+Built specifically for the **Claude Code workflow** — hooks, MCP, and a local dashboard, not a generic SDK you bolt onto something.
+
+## How it works
+
+```
+  Session 1                                  Session 2 (days later)
+  ─────────                                  ─────────────────────
+  You work on auth refactor    ───┐          ┌──► Claude already knows:
+  Claude uses Edit/Write/Bash     │          │    • "Migrated from jwt to iron-session"
+                                  ▼          │    • Hot files: auth/session.ts
+                            ┌──────────┐     │    • Last session left the login route
+                            │ SQLite   │     │      half-wired (blocked)
+                            │ LanceDB  │─────┘
+                            └──────────┘     no re-explaining needed
+```
+
+Two integration modes, use either or both:
+
+**1. Passive (hooks, Claude Code only)** — injects context at session start.
+
+| Hook | What it does |
+|---|---|
+| `PreToolUse` | Builds context block from past sessions and injects it |
+| `PostToolUse` | Classifies and stores each tool use as an observation |
+| `Stop` | Compresses the session, extracts decisions, detects patterns, generates embeddings |
+
+**2. Active (MCP server, works everywhere)** — Claude/Cursor/Windsurf/Cline query memory **during** reasoning via 7 tools:
+
+| Tool | What it enables |
+|---|---|
+| `recall_decisions` | Look up past architectural decisions for a project |
+| `recall_unfinished` | Surface blockers from past sessions |
+| `search_memory` | Semantic + FTS search across all your coding memory |
+| `get_project_history` | Recent session summaries |
+| **`check_intent`** | **Active Guard** — flags actions that contradict past decisions |
+| `record_feedback` | Learns from "useful/irrelevant/wrong" signals |
+| `record_decision` | Persists decisions made in-conversation (never forgotten) |
+
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for setup in each editor.
+
+Nothing leaves your machine.
+
+## Install
+
+### One-command install
+
+**macOS / Linux**
+```bash
+curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell)**
+```powershell
+irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex
+```
+
+That's it — installs Bun if missing, clones the repo into `~/.claude/autoctxd`, installs deps, initializes the DB, and registers the three hooks in your existing `settings.json` (preserving anything already there).
+
+Verify with `autoctxd doctor`. Uninstall cleanly with `bun run scripts/uninstall-hooks.ts`.
+
+### Manual install
+
+If you prefer step-by-step, requires [Bun](https://bun.sh) and Claude Code:
+
+```bash
+cd ~/.claude
+git clone https://github.com/autoctxd/autoctxd.git
+cd autoctxd
+bun install
+bun run src/cli/index.ts init
+bun run scripts/install-hooks.ts   # merges hooks into settings.json
+bun run src/cli/index.ts doctor    # verify
+```
+
+<details>
+<summary>Or if you want to add the hooks manually, here's the block:</summary>
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "bun run ~/.claude/autoctxd/src/hooks/pre-tool-use.ts"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "bun run ~/.claude/autoctxd/src/hooks/post-tool-use.ts"
+      }]
+    }],
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "bun run ~/.claude/autoctxd/src/hooks/stop.ts"
+      }]
+    }]
+  }
+}
+```
+
+
+</details>
+
+Restart Claude Code. The next session starts collecting. The one after that starts getting context.
+
+## CLI
+
+```bash
+# What has autoctxd learned about you?
+bun run src/cli/index.ts stats
+
+# Every decision you've made across projects
+bun run src/cli/index.ts decisions
+
+# Hybrid search (semantic + full-text) across everything
+bun run src/cli/index.ts search "race condition async"
+
+# Drill into one session
+bun run src/cli/index.ts show session <session-id>
+
+# Patterns detected in your workflow
+bun run src/cli/index.ts patterns
+
+# Export a project's memory to markdown
+bun run src/cli/index.ts export ./my-app > context.md
+
+# Re-run the classifier on old observations (after classifier improvements)
+bun run src/cli/index.ts reclassify
+
+# Token accounting: what autoctxd has saved you
+bun run src/cli/index.ts metrics
+
+# Launch the local web dashboard
+bun run src/cli/index.ts dashboard
+# → http://localhost:4589
+
+# Health check your install
+bun run src/cli/index.ts doctor
+```
+
+## Dashboard
+
+![Dashboard](docs/assets/dashboard.png)
+
+Running `autoctxd dashboard` launches a local web UI at `http://localhost:4589`:
+
+- Metric cards: sessions, observations, decisions, projects, context hit rate, avg explore calls, tokens saved
+- Activity timeline of every observation across all projects
+- Architectural decision feed with alternatives and rationale
+- **Decision chains** — automatically detected sequences like `mysql → postgres → sqlite` across sessions
+- Pattern panel (tool preferences, work focus, hotspots, TDD vs fix-first, peak coding hours)
+- Hybrid search (semantic + full-text) with project filter
+
+Everything read-only, everything local. No accounts, no network.
+
+## Debug mode
+
+Set `AUTOCTXD_DEBUG=1` to log every hook invocation to `data/debug.log`:
+
+```bash
+AUTOCTXD_DEBUG=1 claude  # then tail data/debug.log
+```
+
+You'll see what was injected, why, and timings.
+
+## What gets captured
+
+Each `PostToolUse` becomes an **observation**, classified as one of:
+
+`bug_fix` · `refactor` · `new_feature` · `config` · `research` · `test` · `decision` · `blocked` · `deploy` · `other`
+
+The classifier is pure heuristics. Scores each observation 0–10 for importance. Critical files (`auth`, `payment`, `migration`, `schema`) get boosted. Docs/readmes get demoted.
+
+**Decisions** are first-class. Every `bun add`, `npm install`, `cargo add` becomes a stack decision. Every "switched from X to Y" becomes an architectural decision. These never get compressed away.
+
+**Patterns** emerge after 3+ sessions in the same project: tool preferences, work-type focus, file hotspots, TDD vs. fix-first workflows, peak coding hours.
+
+## What gets injected
+
+At session start, `autoctxd` assembles a context block from:
+
+- **Architectural decisions** on this project (all of them, always)
+- **Recent session highlights** (top 3 sessions by recency)
+- **Semantically similar past sessions** (cross-project if relevant)
+- **Hot files** (modified 3+ times recently)
+- **Your patterns in this project**
+
+Format is compact — targets ~600-800 tokens so it doesn't crowd your context window.
+
+## Privacy
+
+Everything stays in `~/.claude/autoctxd/data/`. Delete the folder to wipe all memory. No telemetry, no cloud, no network calls during operation.
+
+For sensitive projects, drop a `.autoctxd-ignore` file at the project root. Patterns follow a `.gitignore`-style subset — a single `*` opts the whole project out. See [SECURITY.md](SECURITY.md) for the full threat model and the list of what does/doesn't get persisted.
+
+## Embedding providers
+
+Pick the right trade-off for your machine and threat model. **TF-IDF is the default** — zero install pain, deterministic, fast. Upgrade when you want richer retrieval.
+
+| Provider | Dim | Latency | Discrimination | Setup |
+|---|---:|---:|---:|---|
+| `tfidf` *(default)* | 128 | **0.1 ms** | gap 0.170, 92% wins | nothing — built in |
+| `minilm` | 384 | 4.5 ms | gap 0.621, **100% wins** | `autoctxd embeddings switch minilm --yes` (~25MB model download on first use) |
+| `ollama` | 768 | varies | run `bun run benchmark:embeddings` on your box | Requires [Ollama](https://ollama.com) running locally with `ollama pull nomic-embed-text` |
+
+*Numbers from `scripts/benchmark-embeddings.ts` over 12 dev-text pairs (anchor / paraphrase / unrelated). "Wins" is the share of pairs where the model puts the paraphrase closer to the anchor than the unrelated text. Higher = better.*
+
+```bash
+# What's active and what's available?
+autoctxd embeddings list
+autoctxd embeddings status
+
+# Switch — re-embeds everything you've stored, automatically
+autoctxd embeddings switch minilm --yes
+
+# Or pin via env (no persistence)
+AUTOCTXD_EMBEDDING=minilm autoctxd ...
+```
+
+The cache is partitioned by provider, so switching back is cheap. `@xenova/transformers` is an `optionalDependency` — if `bun install` fails to fetch it, MiniLM is just unavailable and TF-IDF keeps working.
+
+## Stack
+
+| Component | Tech |
+|---|---|
+| Runtime | Bun |
+| Structured DB | SQLite + FTS5 (full-text search) |
+| Vector DB | LanceDB (dim adapts to active provider) |
+| Embeddings | TF-IDF (default) · MiniLM-L6-v2 via transformers.js · Ollama (any embedding model) |
+| Classification | Keyword + tool/file heuristics |
+
+## Roadmap
+
+- [x] Local web dashboard
+- [x] Decision chains across sessions
+- [x] Token savings metrics
+- [x] One-command installer for all platforms
+- [x] Health-check doctor
+- [x] Integration test suite
+- [x] **MCP server mode** — Claude queries memory actively, not just at session start
+- [x] **Active Guard** — flags actions that contradict past decisions
+- [x] **Feedback loop** — system learns what's useful to each user
+- [x] **Multi-editor** — Cursor, Windsurf, Cline, Claude Desktop, Claude Code
+- [x] **Pluggable embeddings** — TF-IDF default, MiniLM and Ollama opt-in
+- [x] **`.autoctxd-ignore`** — gitignore-style opt-out for sensitive projects
+- [ ] Codebase awareness — integrate git blame + AST analysis
+- [ ] Predictive context — surface what you'll need next based on patterns
+
+## Testing
+
+```bash
+bun test                           # 75 tests, isolated temp DB
+bun run benchmark:embeddings       # cross-provider quality + latency
+bun run typecheck                  # tsc --noEmit
+```
+
+Coverage spans the classifier, compressor, decision extractor, decision chains, ignore matcher, embedding providers, and an end-to-end integration flow. Tests never touch your real memory.
+
+## License
+
+MIT.

package/SECURITY.md

@@ -0,0 +1,81 @@
+# Security & Privacy
+
+`autoctxd` is designed around a single promise: **nothing leaves your machine.** This document explains exactly what that means in practice, what is and isn't persisted, and how to report a vulnerability.
+
+## Privacy model
+
+| Property | Status |
+|---|---|
+| Network calls during operation | None |
+| Telemetry | None |
+| Third-party API keys required | None |
+| LLM calls (yours or ours) | None — embeddings and classification are local heuristics |
+| Cloud sync | None |
+| Data location | `~/.claude/autoctxd/data/` (or `$AUTOCTXD_DATA_DIR` if set) |
+
+The only network activity in the project comes from the one-shot installer scripts (cloning the repo, installing Bun if missing). Once installed, the runtime is fully offline.
+
+## What gets persisted
+
+The hooks intercept Claude Code tool calls and store **summaries** — not raw content:
+
+- **Edit / Write**: the file path plus the first ~80 characters of old/new snippets. The full file content is **not** stored.
+- **Bash**: the command's `description` field if present, otherwise the first command, truncated to 200 characters. **Stdout and stderr are never stored.**
+- **WebFetch / WebSearch / Agent**: prompt and URL/query, truncated to ~160 characters.
+- **Read / Glob / Grep**: counted for metrics only — never stored as observations.
+
+The `tool_response` field exists in the hook payload but is intentionally never read. See `src/hooks/post-tool-use.ts`.
+
+Generated artifacts that live in `~/.claude/autoctxd/data/`:
+
+- `autoctxd.db` — SQLite (sessions, observations, decisions, summaries, FTS index, feedback, MCP access log)
+- `vectors/` — LanceDB vector index of session embeddings
+- `error.log` / `debug.log` — diagnostic logs (only present after errors or when `AUTOCTXD_DEBUG=1`)
+
+## Opting out for sensitive projects
+
+Drop a `.autoctxd-ignore` file at a project's root. Patterns follow a `.gitignore`-style subset (no negation):
+
+```
+# anything matching these is dropped before being written to the DB
+.env
+.env.*
+*.pem
+*.key
+secrets/
+config/credentials.*
+```
+
+Use `*` (or `**`) on a line by itself to opt the entire project out.
+
+The matcher lives in `src/util/ignore.ts` and runs inside the post-tool-use hook before any DB write.
+
+## Wiping all memory
+
+Everything is in one folder. Delete it:
+
+```bash
+rm -rf ~/.claude/autoctxd/data/
+```
+
+Or run `bun run src/cli/index.ts reset` for a structured reset that re-creates an empty database.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security problems.
+
+Email **jatibeliel@gmail.com** with:
+
+- A description of the issue and impact
+- Steps to reproduce
+- The commit hash you tested against
+
+You can expect an initial response within 5 days. If the issue is confirmed, a fix will be prioritized over feature work and credited in the release notes (unless you prefer to remain anonymous).
+
+## Threat model — what `autoctxd` does not protect against
+
+Being clear about scope:
+
+- **A compromised local machine.** If an attacker has read access to `~/.claude/autoctxd/data/`, they can read your observation history. Treat it like any other file in your home directory.
+- **Malicious MCP clients.** The MCP server trusts its caller. Don't expose it over the network.
+- **Hostile prompts in tool inputs.** The classifier is heuristic and won't sanitize adversarial content embedded in commit messages, file contents, or commands. Summaries are length-capped, but the design assumption is that you are the only user driving Claude Code on your machine.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "autoctxd",
+  "version": "0.4.1",
+  "description": "Persistent, local, zero-API memory for Claude Code.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/autoctxd/autoctxd.git"
+  },
+  "homepage": "https://github.com/autoctxd/autoctxd#readme",
+  "bugs": {
+    "url": "https://github.com/autoctxd/autoctxd/issues"
+  },
+  "preferGlobal": true,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "ctx": "bun run src/cli/index.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "dashboard": "bun run src/cli/index.ts dashboard",
+    "doctor": "bun run src/cli/index.ts doctor",
+    "install-hooks": "bun run scripts/install-hooks.ts",
+    "uninstall-hooks": "bun run scripts/uninstall-hooks.ts",
+    "benchmark:embeddings": "bun run scripts/benchmark-embeddings.ts"
+  },
+  "bin": {
+    "autoctxd": "src/cli/index.ts"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "context",
+    "local-first",
+    "sqlite",
+    "lancedb",
+    "ai",
+    "coding-assistant",
+    "mcp",
+    "embeddings"
+  ],
+  "dependencies": {
+    "@lancedb/lancedb": "^0.27.2",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  }
+}

package/scripts/install-hooks.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+// Merges autoctxd hooks into ~/.claude/settings.json, preserving any existing
+// hooks the user has configured. Idempotent: running twice does the same thing.
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "fs";
+import { join, resolve } from "path";
+
+const CTX_ROOT = resolve(join(import.meta.dir, ".."));
+const CLAUDE_DIR = resolve(join(CTX_ROOT, ".."));
+const SETTINGS = join(CLAUDE_DIR, "settings.json");
+
+const HOOK_MAPPING: Record<string, string> = {
+  PreToolUse: "src/hooks/pre-tool-use.ts",
+  PostToolUse: "src/hooks/post-tool-use.ts",
+  Stop: "src/hooks/stop.ts",
+};
+
+function isClaudeCtxHookEntry(entry: any): boolean {
+  return JSON.stringify(entry).includes("autoctxd");
+}
+
+function buildHookEntry(relativePath: string): any {
+  const abs = join(CTX_ROOT, relativePath).replace(/\\/g, "/");
+  return {
+    matcher: "",
+    hooks: [
+      {
+        type: "command",
+        command: `bun run ${abs}`,
+      },
+    ],
+  };
+}
+
+async function main() {
+  let cfg: any = {};
+
+  if (existsSync(SETTINGS)) {
+    // Backup before modifying
+    const backup = `${SETTINGS}.backup.${Date.now()}`;
+    copyFileSync(SETTINGS, backup);
+    console.log(`  Backed up existing settings.json → ${backup}`);
+
+    try {
+      cfg = JSON.parse(readFileSync(SETTINGS, "utf8"));
+    } catch (e) {
+      console.error(`  Cannot parse existing settings.json: ${e}`);
+      console.error(`  Keeping current file as-is. Edit it manually or delete it to proceed.`);
+      process.exit(1);
+    }
+  }
+
+  cfg.hooks ||= {};
+
+  let installed = 0;
+  let skipped = 0;
+
+  for (const [hookName, relPath] of Object.entries(HOOK_MAPPING)) {
+    const current = cfg.hooks[hookName] || [];
+    // Strip any pre-existing autoctxd entries — we'll add a fresh one
+    const cleaned = current.filter((e: any) => !isClaudeCtxHookEntry(e));
+    const skippedHere = current.length - cleaned.length;
+
+    cleaned.push(buildHookEntry(relPath));
+    cfg.hooks[hookName] = cleaned;
+
+    installed++;
+    skipped += skippedHere;
+  }
+
+  writeFileSync(SETTINGS, JSON.stringify(cfg, null, 2) + "\n");
+
+  console.log(`\n  Installed ${installed} autoctxd hooks in ${SETTINGS}`);
+  if (skipped > 0) {
+    console.log(`  Replaced ${skipped} previous autoctxd hook entries.`);
+  }
+  console.log(`\n  Restart Claude Code for hooks to take effect.`);
+}
+
+main();