@malindar/whyline 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test *)",
+      "Bash(npm rebuild *)",
+      "Bash(node-gyp rebuild *)",
+      "Bash(npx node-gyp *)",
+      "Bash(npm install *)",
+      "Bash(node -e \"require\\('better-sqlite3'\\)\")",
+      "Bash(node -e \"require\\('better-sqlite3'\\); console.log\\('ok'\\)\")",
+      "Bash(npm prefix *)",
+      "Bash(npm run *)",
+      "Bash(node *)",
+      "Bash(git -C /Users/malinda.ranasinghe/Documents/contentful/personal/commit-gpt init)",
+      "Bash(git -C /Users/malinda.ranasinghe/Documents/contentful/personal/commit-gpt add .)",
+      "Bash(git -C /Users/malinda.ranasinghe/Documents/contentful/personal/commit-gpt commit -m \"chore: initial commit\")",
+      "Bash(GIT_COMMITTER_NAME=\"Test\" GIT_COMMITTER_EMAIL=\"test@test.com\" GIT_AUTHOR_NAME=\"Test\" GIT_AUTHOR_EMAIL=\"test@test.com\" git -C /Users/malinda.ranasinghe/Documents/contentful/personal/commit-gpt -c commit.gpgsign=false commit -m \"chore: initial commit\")",
+      "Bash(git -C /Users/malinda.ranasinghe/Documents/contentful/moi/gatekeeper log --oneline -5)",
+      "Bash(git -C /Users/malinda.ranasinghe/Documents/contentful/moi/gatekeeper remote get-url origin)",
+      "Read(//Users/malinda.ranasinghe/Documents/contentful/moi/gatekeeper/**)",
+      "Bash(npm unlink *)",
+      "Bash(npm link *)",
+      "Bash(whyline --version)",
+      "Bash(git rm *)",
+      "Bash(npx vitest *)",
+      "Read(//Users/malinda.ranasinghe/Documents/contentful/moi/audit-logging/**)",
+      "Bash(whyline init *)",
+      "Bash(whyline install-claude *)",
+      "Bash(whyline doctor *)",
+      "Bash(whyline list *)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Rebuild native bindings
+        run: npm rebuild better-sqlite3
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Lint
+        run: npm run lint

package/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Rebuild native bindings
+        run: npm rebuild better-sqlite3
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/CLAUDE.md

@@ -0,0 +1,74 @@
+# Claude Instructions for Whyline
+
+You are working on `whyline` — a local-first CLI + MCP server that stores AI coding-session reasoning in SQLite and exposes it to Claude Code.
+
+The MVP is complete. All 7 milestones are built and 160 tests pass.
+
+## Build principles
+
+- Prefer simple local-first implementation.
+- Do not build hosted sync unless explicitly asked.
+- Do not build a UI unless explicitly asked.
+- Do not store raw transcripts by default.
+- Always redact secrets before saving memory.
+- Keep the CLI useful without MCP.
+- Keep the MCP server thin and deterministic.
+- Write tests for database, search, and redaction behavior.
+- Prefer boring, maintainable TypeScript.
+- Use ESM (`"type": "module"`). All imports must use `.js` extensions even for `.ts` source files.
+- `better-sqlite3` is synchronous — do not use async/await in the DB layer.
+
+## What not to build
+
+- Cloud auth or team sharing
+- Hosted vector DB or embeddings service
+- Web UI
+- Background daemons
+- `--manual` interactive mode (deferred to v0.2)
+- PR integrations (deferred to v0.6)
+
+## Schema changes
+
+Any change to the database schema must be added as a new entry in `src/db/schema.ts` `MIGRATIONS[]` array with an incremented version number. Never modify existing migration SQL.
+
+## Adding a new CLI command
+
+1. Create `src/commands/<name>.ts` with a `run<Name>()` export.
+2. Register it in `src/cli.ts`.
+3. Add tests in `tests/<name>.test.ts` using in-memory SQLite.
+
+## Adding a new MCP tool
+
+1. Add a Zod schema to `src/mcp/tools.ts`.
+2. Add the tool descriptor to the `ListToolsRequestSchema` handler in `src/mcp/server.ts`.
+3. Add the `CallToolRequestSchema` case in `src/mcp/server.ts`.
+4. Run `redactSecrets()` on any user-supplied text before saving.
+
+## Keeping instruction files in sync
+
+There are three files that describe how Claude should behave when working with memories. They must always be consistent with each other:
+
+| File | Purpose |
+|------|---------|
+| `src/skill/SKILL.md` | Used when Whyline is loaded as a Claude Code skill |
+| `how-to-run/CLAUDE.md.template` | Injected into user repos by `whyline install-claude` |
+| `docs/architecture.md` | System overview — commands, components, pipelines, directory structure |
+| Deployed `CLAUDE.md` files (e.g. `/Users/malinda.ranasinghe/Documents/contentful/moi/audit-logging/CLAUDE.md`) | Already-wired repos that won't re-run `install-claude` |
+
+**Any time you add or change a feature, ask: does this change how Claude should behave?**
+
+If yes, update all three before closing the task:
+
+1. `src/skill/SKILL.md` — update the relevant section
+2. `how-to-run/CLAUDE.md.template` — apply the same change
+3. Any deployed `CLAUDE.md` files — patch manually (or remind the user to re-run `whyline install-claude`)
+
+Triggers that always require a sync:
+- New MCP tool added (Claude needs to know when and how to call it)
+- New field added to memory responses (e.g. `isStale`, future `confidence`)
+- Search or save workflow changes
+- New quality, staleness, or deduplication rules
+- Changes to what Claude should say when surfacing a memory
+- New CLI command added — update `docs/architecture.md` directory structure and component diagram
+
+If you only update one file, future sessions in repos wired with the old template will behave differently from repos wired with the new one — the instructions will drift.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Malinda Ranasinghe
+
+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,359 @@
+# Whyline
+
+<p align="center">
+  <img src="docs/logo.png" alt="Whyline" width="120" />
+</p>
+
+![npm](https://img.shields.io/npm/v/whyline)
+![license](https://img.shields.io/github/license/malinda1986/whyline)
+![build](https://img.shields.io/github/actions/workflow/status/malinda1986/whyline/ci.yml)
+
+Local-first memory for AI coding sessions.
+
+> Git remembers what changed. Whyline remembers why.
+
+---
+
+## Why this exists
+
+You've been there. You open a file, see a decision made months ago, and have no idea why. The diff shows _what_ changed. The commit message says "fix retention logic." But why 90 days? Why a background job and not a cron? Why not S3?
+
+That context lived in a conversation — and it's gone.
+
+AI coding sessions with tools like Claude produce something valuable beyond the code: the reasoning behind it. The intent, the tradeoffs, the alternatives that were rejected, the risks that were acknowledged. None of that ends up in git. It lives in a chat window and disappears when the context resets.
+
+Whyline captures it.
+
+After each coding session, it stores a concise reasoning record in SQLite on your machine — no cloud, no auth, no new workflow. When you start a new session touching the same files, Claude searches those records automatically and surfaces the relevant context:
+
+> _"Last time we touched this file, we rejected S3 archival because of cost. Still the case?"_
+
+The loop is tight:
+
+- **Start a task** → Claude searches past memories and brings forward relevant decisions
+- **Finish and commit** → Claude synthesizes the session and saves the reasoning automatically
+- **Come back later** → The why is right there, not lost in a chat history
+
+It works through Claude Code's MCP protocol. Two files to set it up in any repo: `.mcp.json` and `CLAUDE.md`.
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/malinda1986/whyline.git
+cd whyline
+npm install
+npm run build
+npm link
+```
+
+### Node version requirement
+
+Node 18 or later. The native `better-sqlite3` bindings must be compiled for your Node version:
+
+```bash
+npm rebuild better-sqlite3
+```
+
+---
+
+## Quick start
+
+### 1. Initialize
+
+```bash
+whyline init
+```
+
+Creates `~/.whyline/` with `memory.db` and `config.json`.
+
+### 2. Wire up a repo
+
+Run this once in each repo you want Whyline to work in:
+
+```bash
+cd your-project
+whyline install-claude
+```
+
+Creates or updates three files:
+- `.mcp.json` — registers the Whyline MCP server (merges with existing entries)
+- `CLAUDE.md` — adds the memory instructions for Claude (appends if the file already exists)
+- `.claude/settings.local.json` — auto-approves the five MCP tool calls so Claude doesn't prompt on every use
+
+```
+  ✓  .mcp.json  (created)
+  ✓  CLAUDE.md  (created)
+  ✓  .claude/settings.local.json  (created)
+
+Done. Open this repo in Claude Code and run `whyline doctor` to verify.
+```
+
+Running it again is safe — it only writes what's missing and never removes existing content.
+
+### 3. Verify setup (optional)
+
+```bash
+whyline doctor
+```
+
+Checks that the DB exists, migrations are current, the binary is on your PATH, you're inside a git repo, `.mcp.json` is configured, `CLAUDE.md` mentions Whyline, and the MCP server starts. Run this whenever something feels off.
+
+```
+  ✓  DB exists  (~/.whyline/memory.db)
+  ✓  Migrations current  (v1)
+  ✓  `whyline` on PATH  (/usr/local/bin/whyline)
+  ✓  Inside a git repo  (/home/user/my-app)
+  ✓  .mcp.json configured  (/home/user/my-app/.mcp.json)
+  ✓  CLAUDE.md mentions Whyline  (/home/user/my-app/CLAUDE.md)
+  ✓  MCP server starts  (tools/list responded)
+
+All checks passed. Whyline is ready.
+```
+
+### 3. Create a memory summary file
+
+Create `memory.md` in your project:
+
+```markdown
+# Memory
+
+Intent:
+Add optimistic comment rendering.
+
+Summary:
+Implemented optimistic rendering for new comments so they appear immediately.
+
+Decision:
+Render comments immediately and reconcile after server ack.
+
+Why:
+Waiting for server confirmation made comment creation feel slow.
+
+Alternatives rejected:
+
+- Server-confirmed rendering only.
+- Polling for new comments after submit.
+
+Risks:
+
+- Duplicate comments during reconnect.
+- Failed server ack needs rollback UI.
+
+Follow-ups:
+
+- Add dedupe reconciliation tests.
+- Add failed-send retry state.
+
+Tags:
+
+- comments
+- sync
+- optimistic-ui
+```
+
+### 4. Save a memory
+
+```bash
+whyline save --commit HEAD --summary-file memory.md
+```
+
+Output:
+
+```
+Saved memory mem_abc12345
+Repo: my-app
+Commit: abc12345
+Files: 3
+```
+
+### 5. Search memories
+
+```bash
+whyline search "why optimistic comments?"
+whyline search "refresh token" --file src/auth/session.ts
+whyline search "checkout validation" --limit 5
+
+# Filter by tag (repeat for AND semantics)
+whyline search "" --tag auth --tag security
+
+# Filter by date
+whyline search "" --since 2025-01-01
+whyline search "" --before 2025-06-30
+whyline search "token" --tag auth --since 2025-01-01 --before 2025-12-31
+```
+
+### 6. Browse all memories
+
+```bash
+whyline list              # all memories, newest first
+whyline list --repo       # scoped to the current git repo
+whyline list --limit 5    # cap results
+```
+
+### 7. Show a memory
+
+```bash
+whyline show mem_abc12345
+whyline show --commit abc12345
+```
+
+### 8. Edit a memory
+
+Open a memory in `$EDITOR` as markdown, save changes back to the DB:
+
+```bash
+whyline edit mem_abc12345
+```
+
+### 9. Delete a memory
+
+```bash
+whyline delete mem_abc12345          # prompts for confirmation
+whyline delete mem_abc12345 --force  # skips confirmation
+```
+
+### 10. Export & import memories
+
+```bash
+# Export all memories as JSON (default)
+whyline export > backup.json
+
+# Export as markdown
+whyline export --format md --output memories.md
+
+# Export only this repo's memories, filtered by tag and date
+whyline export --repo --tag auth --since 2025-01-01 --output auth-memories.json
+
+# Import from a previous export (skips duplicates, redacts any exposed secrets)
+whyline import backup.json
+```
+
+### 11. Storage stats
+
+```bash
+whyline stats
+```
+
+Output:
+```
+Total memories:  42
+Repos tracked:   3
+Oldest memory:   1/15/2025
+Newest memory:   5/13/2026
+
+Most referenced files:
+  12x  src/auth/session.ts
+   8x  src/comments/sync.ts
+   5x  src/db/migrations.ts
+```
+
+### 12. Start MCP server
+
+```bash
+whyline mcp
+```
+
+---
+
+## Configure Claude Code
+
+Add `.mcp.json` to your repo root:
+
+```json
+{
+  "mcpServers": {
+    "whyline": {
+      "command": "whyline",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then add the skill to Claude Code by referencing `src/skill/SKILL.md` in your project's `CLAUDE.md`.
+
+---
+
+## Memory summary file format
+
+The parser is forgiving — missing fields fall back to safe defaults.
+
+Supported headings:
+
+| Heading                  | Type        | Default                   |
+| ------------------------ | ----------- | ------------------------- |
+| `Task:`                  | text        | _(omitted)_               |
+| `Intent:`                | text        | `"Unspecified intent"`    |
+| `Summary:`               | text        | _(full file content)_     |
+| `Decision:`              | text        | `"Unspecified decision"`  |
+| `Why:`                   | text        | `"Unspecified rationale"` |
+| `Alternatives rejected:` | bullet list | `[]`                      |
+| `Risks:`                 | bullet list | `[]`                      |
+| `Follow-ups:`            | bullet list | `[]`                      |
+| `Tags:`                  | bullet list | `[]`                      |
+
+---
+
+## MCP tools
+
+Claude Code can call these tools via the MCP server:
+
+| Tool                   | Description                           |
+| ---------------------- | ------------------------------------- |
+| `search_coding_memory` | Search memories by keyword            |
+| `save_coding_memory`   | Save a new memory                     |
+| `get_commit_memory`    | Get memories for a specific commit    |
+| `get_file_memories`    | Get memories touching a specific file |
+
+---
+
+## Secret redaction
+
+All text is automatically scanned before saving. The following are redacted and replaced with `[REDACTED_SECRET]`:
+
+- GitHub tokens (`ghp_`, `gho_`, `ghs_`)
+- npm tokens (`npm_`)
+- AWS access keys (`AKIA...`)
+- Bearer tokens
+- `.env`-style secrets (`API_KEY=`, `SECRET=`, etc.)
+- PEM private key blocks
+
+---
+
+## Post-commit hook (optional)
+
+Copy `src/hooks/post-commit.sample.sh` to `.git/hooks/post-commit` and make it executable:
+
+```bash
+cp src/hooks/post-commit.sample.sh .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+This reminds you to save a memory after each commit.
+
+---
+
+## Development
+
+```bash
+npm run dev -- init           # run via tsx without building
+npm test                      # run tests
+npm run build                 # compile to dist/
+npm run lint                  # eslint
+```
+
+---
+
+## Storage
+
+All data is stored locally at `~/.whyline/memory.db` (SQLite). The repository is never modified unless you explicitly install the post-commit hook.
+
+---
+
+## Roadmap
+
+- v0.6 — `--manual` interactive save mode
+- v0.6 — GitHub PR integration
+- v0.7 — team-shared memory server

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runInit } from "./commands/init.js";
+function collect(val, acc) {
+    acc.push(val);
+    return acc;
+}
+const program = new Command();
+program
+    .name("whyline")
+    .description("Local-first memory for AI coding sessions")
+    .version("0.1.0");
+program.command("init").description("Initialize whyline storage").action(() => runInit());
+program
+    .command("doctor")
+    .description("Check whyline setup and diagnose configuration problems")
+    .action(async () => {
+    const { runDoctor } = await import("./commands/doctor.js");
+    await runDoctor();
+});
+program
+    .command("install-claude")
+    .description("Create or update .mcp.json, CLAUDE.md, and .claude/settings.local.json for this repo")
+    .option("--repo-path <path>", "Target repo path (defaults to current directory)")
+    .action(async (options) => {
+    const { runInstallClaude } = await import("./commands/install-claude.js");
+    await runInstallClaude(options);
+});
+program
+    .command("save")
+    .description("Save a coding memory")
+    .requiredOption("--commit <ref>", "Git commit ref")
+    .requiredOption("--summary-file <path>", "Path to markdown summary file")
+    .action(async (options) => {
+    const { runSave } = await import("./commands/save.js");
+    await runSave(options);
+});
+program
+    .command("search <query>")
+    .description("Search coding memories")
+    .option("--file <path>", "Filter by file path")
+    .option("--tag <tag>", "Filter by tag (repeat for multiple)", collect, [])
+    .option("--since <date>", "Only memories created after this date (e.g. 2025-01-01)")
+    .option("--before <date>", "Only memories created before this date (e.g. 2025-12-31)")
+    .option("--limit <n>", "Max results", "10")
+    .action(async (query, options) => {
+    const { runSearch } = await import("./commands/search.js");
+    await runSearch(query, options);
+});
+program
+    .command("show [id]")
+    .description("Show a single memory")
+    .option("--commit <sha>", "Find by commit SHA instead")
+    .action(async (id, options) => {
+    const { runShow } = await import("./commands/show.js");
+    await runShow(id, options);
+});
+program
+    .command("list")
+    .description("List stored memories in reverse chronological order")
+    .option("--repo", "Limit to the current git repository", false)
+    .option("--limit <n>", "Max results", "20")
+    .action(async (options) => {
+    const { runList } = await import("./commands/list.js");
+    await runList(options);
+});
+program
+    .command("delete <id>")
+    .description("Delete a memory by ID")
+    .option("--force", "Skip confirmation prompt", false)
+    .action(async (id, options) => {
+    const { runDelete } = await import("./commands/delete.js");
+    await runDelete(id, options);
+});
+program
+    .command("stats")
+    .description("Show memory storage statistics")
+    .action(async () => {
+    const { runStats } = await import("./commands/stats.js");
+    await runStats();
+});
+program
+    .command("edit <id>")
+    .description("Edit a memory in $EDITOR")
+    .action(async (id) => {
+    const { runEdit } = await import("./commands/edit.js");
+    await runEdit(id);
+});
+program
+    .command("export")
+    .description("Export memories to JSON or markdown")
+    .option("--format <fmt>", "Output format: json or md", "json")
+    .option("--output <path>", "Write to file instead of stdout")
+    .option("--repo", "Limit to the current git repository", false)
+    .option("--tag <tag>", "Filter by tag (repeat for multiple)", collect, [])
+    .option("--since <date>", "Only memories created after this date (e.g. 2025-01-01)")
+    .option("--before <date>", "Only memories created before this date (e.g. 2025-12-31)")
+    .action(async (options) => {
+    const { runExport } = await import("./commands/export.js");
+    await runExport(options);
+});
+program
+    .command("import <file>")
+    .description("Import memories from a JSON export file")
+    .action(async (file) => {
+    const { runImport } = await import("./commands/import.js");
+    await runImport(file);
+});
+program
+    .command("summarize <id>")
+    .description("Use the Claude API to improve a saved memory's quality (requires ANTHROPIC_API_KEY)")
+    .option("--force", "Apply improvements without confirmation prompt", false)
+    .action(async (id, options) => {
+    const { runSummarize } = await import("./commands/summarize.js");
+    await runSummarize(id, options);
+});
+program
+    .command("mcp")
+    .description("Start MCP server over stdio")
+    .action(async () => {
+    const { runMcp } = await import("./commands/mcp.js");
+    await runMcp();
+});
+program.parse();
+//# sourceMappingURL=cli.js.map