threadctx-mcp 0.2.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 threadctx
+
+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

@@ -1,8 +1,11 @@
 # threadctx-mcp
 
 Shared memory MCP server for AI coding agents. Works identically with
-**Claude Code** and **Cursor** — same package, same config shape, no
-per-client integration work.
+**Claude Code**, **Cursor**, and any MCP client — same package, same config
+shape, no per-client integration work. On first start it also drops a
+"check team memory" instruction into whichever agents' rule files your repo
+uses (`AGENTS.md`, `CLAUDE.md`, Copilot, Windsurf, Cline, Gemini) so the
+memory actually gets read, not just exposed.
 
 ## Modes
 
@@ -21,11 +24,13 @@ per-client integration work.
 ## Quick start
 
 ```bash
-# Local mode — nothing to configure
+# Local mode — nothing to configure. Also auto-adds the "check team memory"
+# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any
+# detected tool-specific files) on first start.
 npx threadctx-mcp
 
-# Optional: write a committable config + drop "check team memory" into your
-# agent's project rules (CLAUDE.md / .cursorrules). Works in local mode too.
+# Optional: write a committable .threadctx.json config, or re-apply the
+# project-rules block explicitly.
 npx threadctx-mcp init
 
 # Cloud mode — prints the exact MCP config block to paste
@@ -42,11 +47,40 @@ The key is read from the `THREADCTX_API_KEY` environment variable at
 runtime (set it in your MCP client's `env` block, as shown below), so
 secrets stay out of version control by construction.
 
-`init` also adds a small, clearly-marked block to your `CLAUDE.md` and
-`.cursorrules` instructing the agent to call `memory_query` before a task
-and `memory_write` after — this is what makes the memory reliably get
-*read*, since MCP tools are pull-based (pass `--no-rules` to skip). Re-running
-`init` refreshes that block in place instead of duplicating it.
+threadctx also adds a small, clearly-marked instruction to your project
+rules telling the agent to call `memory_query` before a task and
+`memory_write` after. It writes the two universal files every time —
+[`AGENTS.md`](https://agents.md) (the cross-tool standard read by Copilot,
+Cursor, Windsurf, Zed, Codex, Aider, and ~24 others) and `CLAUDE.md`
+(Claude Code's richer native format) — plus `.cursor/rules/threadctx.mdc`.
+It then adds a tool-specific file **only when that tool's footprint is
+detected in the repo**, so it never litters your project with rule files for
+tools you don't use:
+
+| Tool | File written | Written when |
+|---|---|---|
+| Cross-tool standard | `AGENTS.md` | always |
+| Claude Code | `CLAUDE.md` | always |
+| Cursor | `.cursor/rules/threadctx.mdc` | always |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.github/` exists |
+| Windsurf | `.windsurf/rules/threadctx.md` | `.windsurf/` exists |
+| Cline | `.clinerules/threadctx.md` | `.clinerules` exists |
+| Gemini CLI | `GEMINI.md` | `.gemini/` exists |
+
+Shared files (`AGENTS.md`, `CLAUDE.md`, Copilot, Gemini) get a marker-fenced
+block spliced in, preserving your own content around it; dedicated files are
+owned in full. **This happens automatically the first time the server starts
+in a project — you don't need to run `init` for it.** Running `init` just
+triggers it explicitly and prints the result; either way it's idempotent
+(safe to re-run, never duplicates). Opt out entirely with
+`THREADCTX_NO_AUTO_RULES=1`, or per-`init`-call with `--no-rules`.
+
+The same instruction is also sent as part of the MCP `initialize` handshake
+itself (the protocol's `instructions` field), so it reaches the model even
+before any rules file exists, and for clients that don't read project-rules
+files at all. The file-based rules are belt-and-suspenders on top of that,
+since not every MCP client is guaranteed to surface `instructions`
+prominently.
 
 ## Claude Code setup
 
@@ -91,6 +125,33 @@ Cursor Settings → Tools & MCP):
 That's it — the same package and config work in both clients because
 MCP is a portable, open protocol.
 
+## Passive capture — turn git history into memory
+
+Memory shouldn't depend on an agent *remembering* to call `memory_write`.
+`threadctx capture` reads the commits landed since its last run, uses **your
+own LLM provider key** to distill the genuinely reusable decisions and
+gotchas (skipping trivial commits), dedups them against what's already
+stored, and writes the survivors. It's tool-agnostic — it doesn't matter
+whether the work happened in Claude Code, Cursor, Copilot, or a plain editor.
+
+```bash
+# Off by default because it calls an LLM (billed to your provider). Enable it:
+export THREADCTX_CAPTURE_ENABLED=1
+export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY
+
+npx threadctx-mcp capture --dry-run     # preview what it would store
+npx threadctx-mcp capture               # store them (incremental since last run)
+npx threadctx-mcp capture --since=v1.2.0 --diffs   # a range, with patches
+
+# Scaffold a GitHub Action that captures every merged PR automatically:
+npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml
+```
+
+Capture calls your LLM provider directly — nothing is routed through
+threadctx's servers, so local mode keeps its "no network call beyond your own
+LLM provider" promise. It is **off unless `THREADCTX_CAPTURE_ENABLED=1`** (or
+a one-off `--force`), so it can never run up token cost as a side effect.
+
 ## Environment variables
 
 | Variable | Required | Description |
@@ -100,6 +161,11 @@ MCP is a portable, open protocol.
 | `THREADCTX_API_URL` | no | defaults to `https://threadctx.dev/api/v1`; override for self-hosting |
 | `THREADCTX_REPO` | no | overrides repo auto-detection from `git remote` |
 | `THREADCTX_DB_PATH` | no | local-mode store path; defaults to `~/.threadctx/local.json` |
+| `THREADCTX_NO_AUTO_RULES` | no | set to `1` to disable auto-injecting agent rule files on server start |
+| `THREADCTX_CAPTURE_ENABLED` | for `capture` | set to `1` to enable the LLM-backed `capture` command (off by default) |
+| `THREADCTX_CAPTURE_PROVIDER` | no | force `anthropic` or `openai` when both keys are present |
+| `THREADCTX_CAPTURE_MODEL` | no | override the extraction model (defaults: Haiku / gpt-4o-mini) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | for `capture` | your own provider key; capture calls it directly |
 
 ## Local development
 
@@ -120,17 +186,23 @@ npm run build   # compiles to dist/ for publishing
   hits)`) so the same string is recognizable whether you're reading
   Claude Code's terminal output or Cursor's agent panel.
 
-Tool descriptions are deliberately written to bias the model toward
-calling `memory_query` proactively — MCP is pull-based, so the agent has
-to be prompted by the description to use it; it isn't automatic. For the
-most reliable behavior, run `npx threadctx-mcp init`, which adds an explicit
-"check team memory before/after each task" instruction to your `CLAUDE.md`
-and `.cursorrules`.
+Tool descriptions are written to bias the model toward calling
+`memory_query` proactively, and — as of 0.3.0 — the server reinforces this
+two more ways with zero setup required: the MCP `initialize` response
+carries the same instruction to every connecting client, and `CLAUDE.md` /
+`.cursor/rules/threadctx.mdc` get it auto-injected on first start. MCP tools
+are still fundamentally pull-based (no mechanism can force a tool call), but
+these three layers together are the strongest guarantee we can build.
 
 ## CLI subcommands
 
 | Command | What it does |
 |---|---|
-| `npx threadctx-mcp` | Runs the MCP server (this is what Claude Code / Cursor launch). |
-| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | Writes `.threadctx.json` and the project-rules block. |
+| `npx threadctx-mcp` | Runs the MCP server (this is what Claude Code / Cursor launch). Auto-injects project rules on first start in a project. |
+| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | Writes `.threadctx.json` and explicitly (re-)applies the project-rules files. |
 | `npx threadctx-mcp list [--all] [--full] [--json]` | Shows what's stored in the local on-disk memory. |
+| `npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow]` | Distills recent git history into memories via your own LLM key. Off unless `THREADCTX_CAPTURE_ENABLED=1` (or `--force`). |
+
+Browse, search, edit, and prune team (cloud) memory in a human dashboard at
+[threadctx.dev/dashboard](https://threadctx.dev/dashboard) — sign in with your
+team API key.

package/dist/capture.d.ts

@@ -0,0 +1,23 @@
+interface ExtractedMemory {
+    content: string;
+    tags: string[];
+}
+export declare function coerceMemories(raw: unknown[]): ExtractedMemory[];
+interface CaptureFlags {
+    since?: string;
+    max: number;
+    dryRun: boolean;
+    diffs: boolean;
+    model?: string;
+    force: boolean;
+    printWorkflow: boolean;
+}
+export declare const WORKFLOW_TEMPLATE = "# Auto-distill merged PRs into threadctx team memory.\n# Requires two repo secrets:\n#   THREADCTX_API_KEY  \u2013 your threadctx cloud key (Team plan)\n#   ANTHROPIC_API_KEY  \u2013 or OPENAI_API_KEY; capture uses your own provider\nname: threadctx capture\n\non:\n  pull_request:\n    types: [closed]\n    branches: [main]\n\njobs:\n  capture:\n    # Only on real merges, and only when the secret is present (skips on forks).\n    if: github.event.pull_request.merged == true\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0 # full history so capture can see the merged commits\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n      - name: Distill merged commits into team memory\n        env:\n          THREADCTX_CAPTURE_ENABLED: '1'\n          THREADCTX_MODE: cloud\n          THREADCTX_API_KEY: ${{ secrets.THREADCTX_API_KEY }}\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n        run: npx -y threadctx-mcp capture --since ${{ github.event.pull_request.base.sha }}\n";
+/**
+ * `threadctx capture [--since=<ref>] [--max=N] [--diffs] [--dry-run] [--model=ID]`
+ * Distills commits landed since the last capture (or the last N commits) into
+ * memories using your own LLM provider key, dedups against what's stored, and
+ * writes the survivors to the local or cloud store.
+ */
+export declare function runCapture(flags: CaptureFlags): Promise<void>;
+export {};

package/dist/capture.js

@@ -0,0 +1,291 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { loadConfig } from './config.js';
+import { LocalStore } from './local-store.js';
+import { CloudClient } from './cloud-client.js';
+import { complete, detectProvider, parseJsonArray } from './llm.js';
+const US = '\x1f'; // unit separator between fields
+const RS = '\x1e'; // record separator between commits
+const MAX_BODY_CHARS = 1200; // bound a runaway commit body's token cost
+function git(args) {
+    return execFileSync('git', args, { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+}
+function isGitRepo() {
+    try {
+        git(['rev-parse', '--is-inside-work-tree']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isAncestor(sha) {
+    try {
+        execFileSync('git', ['merge-base', '--is-ancestor', sha, 'HEAD'], {
+            cwd: process.cwd(),
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Per-repo capture state (last commit we've already distilled) lives next to the
+// local store, keyed by repo slug, so re-running capture is incremental and
+// idempotent — you only ever process commits landed since the last run.
+function markerPath(config) {
+    const slug = config.repo.replace(/[^a-zA-Z0-9._-]+/g, '__');
+    return join(dirname(config.dbPath), 'capture', `${slug}.json`);
+}
+function readLastSha(config) {
+    const path = markerPath(config);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8')).lastSha ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLastSha(config, sha) {
+    const path = markerPath(config);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ lastSha: sha, updatedAt: new Date().toISOString() }, null, 2) + '\n');
+}
+function collectCommits(range, max) {
+    const format = ['%H', '%ad', '%s', '%b'].join(US) + RS;
+    const args = ['log', '--no-merges', '--date=short', `--pretty=format:${format}`];
+    if (range)
+        args.push(range);
+    else
+        args.push(`-n`, String(max));
+    const raw = git(args);
+    if (!raw)
+        return [];
+    return raw
+        .split(RS)
+        .map((rec) => rec.replace(/^\s+/, ''))
+        .filter(Boolean)
+        .map((rec) => {
+        const [hash, date, subject, body = ''] = rec.split(US);
+        return { hash, date, subject, body: body.trim().slice(0, MAX_BODY_CHARS) };
+    })
+        .filter((c) => c.hash && c.subject);
+}
+const SYSTEM_PROMPT = [
+    'You extract durable, reusable engineering knowledge from git history for a team memory system.',
+    'A good memory is a non-obvious decision, a fix for a tricky bug, a gotcha, a constraint, or an',
+    'architectural choice that would save a teammate real time later. Write each as a SELF-CONTAINED',
+    'note (2-5 sentences) with enough context to be understood months later by someone who was not there.',
+    '',
+    'STRICT RULES:',
+    '- Skip trivial/mechanical commits: version bumps, formatting, lint, typo fixes, routine dependency',
+    '  bumps, "wip", merge commits, and anything with no reusable lesson.',
+    '- Do NOT restate the diff; capture the WHY and the lesson, not the change.',
+    '- Do NOT duplicate anything in the "Already stored" list; skip near-duplicates.',
+    '- Prefer fewer, higher-quality notes. Returning an empty array is correct when nothing qualifies.',
+    '- Output ONLY a JSON array. Each item: {"content": string, "tags": string[] (1-4 short tags)}.',
+].join('\n');
+function buildUserPrompt(repo, commits, existing, includeDiffs) {
+    const existingBlock = existing.length
+        ? existing.map((c) => `- ${c.replace(/\s+/g, ' ').slice(0, 240)}`).join('\n')
+        : '(none)';
+    const commitBlock = commits
+        .map((c) => {
+        const diff = includeDiffs ? diffFor(c.hash) : '';
+        return [
+            `commit ${c.hash.slice(0, 10)} (${c.date})`,
+            `subject: ${c.subject}`,
+            c.body ? `body:\n${c.body}` : '',
+            diff ? `diff (truncated):\n${diff}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+    })
+        .join('\n\n---\n\n');
+    return [
+        `Repository: ${repo}`,
+        '',
+        'Already stored (do not duplicate these):',
+        existingBlock,
+        '',
+        `New commits to distill (${commits.length}):`,
+        '',
+        commitBlock,
+        '',
+        'Return the JSON array now.',
+    ].join('\n');
+}
+function diffFor(hash) {
+    try {
+        // Names + patch, but bounded: full diffs blow up tokens and can leak secrets,
+        // so --diffs is opt-in and each commit's patch is hard-capped.
+        return git(['show', '--no-color', '--stat', '--patch', '--format=', hash]).slice(0, 3000);
+    }
+    catch {
+        return '';
+    }
+}
+export function coerceMemories(raw) {
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const content = typeof obj.content === 'string' ? obj.content.trim() : '';
+        if (content.length < 20)
+            continue; // reject empty/degenerate notes
+        const tags = Array.isArray(obj.tags)
+            ? obj.tags.filter((t) => typeof t === 'string').map((t) => t.trim().slice(0, 50)).slice(0, 4)
+            : [];
+        out.push({ content: content.slice(0, 4000), tags });
+    }
+    return out;
+}
+// A ready-to-commit GitHub Actions workflow that runs capture automatically when
+// a PR merges — this is what makes capture a passive, always-on team habit rather
+// than a manual chore. Printed by `threadctx capture --print-workflow` so a team
+// can scaffold it in one line:
+//   npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml
+// It captures exactly the merged PR's commits (--since the base sha), and is
+// itself gated by THREADCTX_CAPTURE_ENABLED so it never runs unless configured.
+export const WORKFLOW_TEMPLATE = `# Auto-distill merged PRs into threadctx team memory.
+# Requires two repo secrets:
+#   THREADCTX_API_KEY  – your threadctx cloud key (Team plan)
+#   ANTHROPIC_API_KEY  – or OPENAI_API_KEY; capture uses your own provider
+name: threadctx capture
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  capture:
+    # Only on real merges, and only when the secret is present (skips on forks).
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so capture can see the merged commits
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Distill merged commits into team memory
+        env:
+          THREADCTX_CAPTURE_ENABLED: '1'
+          THREADCTX_MODE: cloud
+          THREADCTX_API_KEY: \${{ secrets.THREADCTX_API_KEY }}
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+        run: npx -y threadctx-mcp capture --since \${{ github.event.pull_request.base.sha }}
+`;
+// The master on/off switch for the only LLM-billed feature. Accepts the usual
+// truthy spellings; anything else (including unset) means OFF.
+function captureEnabled() {
+    const v = (process.env.THREADCTX_CAPTURE_ENABLED ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/**
+ * `threadctx capture [--since=<ref>] [--max=N] [--diffs] [--dry-run] [--model=ID]`
+ * Distills commits landed since the last capture (or the last N commits) into
+ * memories using your own LLM provider key, dedups against what's stored, and
+ * writes the survivors to the local or cloud store.
+ */
+export async function runCapture(flags) {
+    // Print-only: scaffold the CI workflow. Costs nothing, so it runs before any
+    // enable-gate or git checks.
+    if (flags.printWorkflow) {
+        process.stdout.write(WORKFLOW_TEMPLATE);
+        return;
+    }
+    // Capture is the only feature that calls an LLM, so it's OFF by default and
+    // must be explicitly switched on. This guarantees zero token spend unless a
+    // human/CI opts in — nothing here ever runs an LLM as a side effect of normal
+    // MCP usage. Enable with THREADCTX_CAPTURE_ENABLED=1 (or --force for a one-off).
+    if (!captureEnabled() && !flags.force) {
+        console.error('[threadctx] `capture` is off by default because it calls an LLM (billed to your own');
+        console.error('[threadctx] provider key). Turn it on explicitly when you want it:');
+        console.error('[threadctx]   export THREADCTX_CAPTURE_ENABLED=1   # persistent on/off switch');
+        console.error('[threadctx]   npx threadctx-mcp capture --dry-run   # or add --force for a one-off run');
+        process.exit(1);
+    }
+    if (!isGitRepo()) {
+        console.error('[threadctx] `capture` must run inside a git repository (none found here).');
+        process.exit(1);
+    }
+    const provider = detectProvider(flags.model);
+    if (!provider) {
+        console.error('[threadctx] capture needs your own LLM provider key to distill commits.');
+        console.error('[threadctx] Set ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment and re-run.');
+        console.error('[threadctx] (Nothing is sent to threadctx servers — capture calls your provider directly.)');
+        process.exit(1);
+    }
+    const config = loadConfig();
+    // Resolve the commit range: explicit --since wins, else incremental from the
+    // last captured SHA (if it's still an ancestor of HEAD), else last --max.
+    let range = null;
+    if (flags.since) {
+        range = `${flags.since}..HEAD`;
+    }
+    else {
+        const lastSha = readLastSha(config);
+        if (lastSha && isAncestor(lastSha))
+            range = `${lastSha}..HEAD`;
+    }
+    const commits = collectCommits(range, flags.max);
+    if (commits.length === 0) {
+        console.log('[threadctx] No new commits to capture. You are up to date.');
+        return;
+    }
+    const head = git(['rev-parse', 'HEAD']);
+    // Existing memories for dedup context (best-effort in cloud mode).
+    const localStore = config.mode === 'cloud' && config.apiKey ? null : new LocalStore(config.dbPath);
+    const cloudClient = config.mode === 'cloud' && config.apiKey
+        ? new CloudClient(config.apiUrl, config.apiKey, config.actorId)
+        : null;
+    const existing = localStore
+        ? localStore.list(config.repo).map((m) => m.content)
+        : (await cloudClient.recent(config.repo, 100)).map((m) => m.content);
+    console.log(`[threadctx] Distilling ${commits.length} commit${commits.length === 1 ? '' : 's'} for ${config.repo} ` +
+        `via ${provider.name} (${provider.model})…`);
+    const responseText = await complete(provider, SYSTEM_PROMPT, buildUserPrompt(config.repo, commits, existing, flags.diffs));
+    const memories = coerceMemories(parseJsonArray(responseText));
+    if (memories.length === 0) {
+        console.log('[threadctx] Nothing worth remembering in these commits (that is a fine outcome).');
+        if (!flags.dryRun)
+            writeLastSha(config, head);
+        return;
+    }
+    console.log(`\n[threadctx] ${memories.length} candidate ${memories.length === 1 ? 'memory' : 'memories'}:\n`);
+    memories.forEach((m, i) => {
+        console.log(`${i + 1}. ${m.content}`);
+        if (m.tags.length)
+            console.log(`   tags: ${m.tags.join(', ')}`);
+        console.log('');
+    });
+    if (flags.dryRun) {
+        console.log('[threadctx] --dry-run: nothing written. Re-run without --dry-run to store these.');
+        return;
+    }
+    let stored = 0;
+    for (const m of memories) {
+        try {
+            if (localStore)
+                localStore.write(config.repo, m.content, m.tags);
+            else
+                await cloudClient.write(config.repo, m.content, m.tags);
+            stored += 1;
+        }
+        catch (err) {
+            console.error(`[threadctx] Failed to store a memory: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    writeLastSha(config, head);
+    console.log(`[threadctx] Stored ${stored} ${stored === 1 ? 'memory' : 'memories'} to ${localStore ? 'the local store' : 'threadctx cloud'}. Your team can now query these.`);
+}

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from './config.js';
 import { LocalStore } from './local-store.js';
+import { applyRules } from './rules.js';
+import { runCapture } from './capture.js';
 import { startServer } from './server.js';
 const [, , command, ...rest] = process.argv;
 function parseFlags(args) {
@@ -19,53 +21,6 @@ function parseFlags(args) {
     }
     return flags;
 }
-// The exact instruction block we drop into an agent's project rules. MCP is
-// pull-based — the model only calls memory_query/memory_write if something tells
-// it to — so this is the single highest-leverage thing for making the memory
-// actually get read. Fenced by markers so re-running `init` updates in place
-// instead of appending duplicates.
-const RULES_START = '<!-- threadctx:start (managed — edit above/below, not between) -->';
-const RULES_END = '<!-- threadctx:end -->';
-const RULES_BODY = [
-    '## Team memory (threadctx)',
-    '',
-    '- **Before** starting any non-trivial task, call `memory_query` with a short',
-    '  description of what you are about to do. Check for prior decisions, fixes,',
-    '  and gotchas on this repo before writing code — not after.',
-    '- **After** resolving a non-obvious bug, making an architectural decision, or',
-    '  learning something that would save a teammate time, call `memory_write` to',
-    '  save it. Write it so a future reader has full context.',
-].join('\n');
-/**
- * Insert (or refresh) the threadctx rules block in a project rules file,
- * idempotently. Creates the file if missing. Returns what happened so the
- * caller can report it honestly.
- */
-function upsertRulesBlock(filePath) {
-    const block = `${RULES_START}\n${RULES_BODY}\n${RULES_END}\n`;
-    if (!existsSync(filePath)) {
-        writeFileSync(filePath, block);
-        return 'created';
-    }
-    const existing = readFileSync(filePath, 'utf-8');
-    const startIdx = existing.indexOf(RULES_START);
-    if (startIdx !== -1) {
-        const endIdx = existing.indexOf(RULES_END, startIdx);
-        if (endIdx !== -1) {
-            const before = existing.slice(0, startIdx);
-            const after = existing.slice(endIdx + RULES_END.length);
-            const next = `${before}${block.trimEnd()}${after}`;
-            if (next === existing)
-                return 'unchanged';
-            writeFileSync(filePath, next);
-            return 'updated';
-        }
-    }
-    // No managed block yet — append one, keeping the user's existing content.
-    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
-    writeFileSync(filePath, `${existing}${sep}${block}`);
-    return 'updated';
-}
 function runInit(args) {
     const flags = parseFlags(args);
     const mode = flags.mode === 'cloud' ? 'cloud' : 'local';
@@ -87,14 +42,17 @@ function runInit(args) {
     writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
     console.log(`✅ Wrote ${configPath} (mode: ${mode}) — safe to commit, contains no secret.`);
     // Drop the "always check team memory" instruction into the agent's project
-    // rules so the tools actually get used. Opt out with --no-rules.
+    // rules so the tools actually get used, even for clients that don't surface
+    // MCP's `initialize.instructions` prominently. Opt out with --no-rules. The
+    // server also does this automatically on every start (see server.ts) — this
+    // just lets you trigger it explicitly and see the result immediately.
     if (flags['no-rules'] !== true) {
-        for (const rulesFile of ['CLAUDE.md', '.cursorrules']) {
-            const rulesPath = join(process.cwd(), rulesFile);
-            const result = upsertRulesBlock(rulesPath);
-            const verb = result === 'created' ? 'Created' : result === 'updated' ? 'Updated' : 'Already current in';
-            console.log(`✅ ${verb} ${rulesFile} — tells your agent to check team memory each task.`);
+        const describe = (r) => (r === 'created' ? 'Created' : r === 'updated' ? 'Updated' : 'Already current');
+        for (const rule of applyRules(process.cwd())) {
+            console.log(`✅ ${describe(rule.result)}: ${rule.label} — tells your agent to check team memory each task.`);
         }
+        console.log('   (AGENTS.md + CLAUDE.md are always written; Copilot/Windsurf/Cline/Gemini files are added only');
+        console.log('   when that tool is detected in the repo. Opt out entirely with --no-rules.)');
     }
     console.log('');
     if (mode === 'cloud') {
@@ -195,6 +153,20 @@ async function main() {
         runList(rest);
         return;
     }
+    if (command === 'capture') {
+        const flags = parseFlags(rest);
+        const parsedMax = typeof flags.max === 'string' ? parseInt(flags.max, 10) : NaN;
+        await runCapture({
+            since: typeof flags.since === 'string' ? flags.since : undefined,
+            max: Number.isFinite(parsedMax) && parsedMax > 0 ? parsedMax : 30,
+            dryRun: flags['dry-run'] === true,
+            diffs: flags.diffs === true,
+            model: typeof flags.model === 'string' ? flags.model : undefined,
+            force: flags.force === true,
+            printWorkflow: flags['print-workflow'] === true,
+        });
+        return;
+    }
     // No subcommand: this is what Claude Code / Cursor actually launch as the
     // MCP server process (they invoke `npx threadctx-mcp` with no arguments).
     await startServer();

package/dist/cloud-client.d.ts

@@ -9,6 +9,17 @@ export interface CloudQueryResponse {
         num_candidates: number;
     };
 }
+export interface CloudMemory {
+    id: string;
+    repo: string;
+    content: string;
+    tags: string[];
+    created_at: string;
+}
+export interface CloudListResponse {
+    memories: CloudMemory[];
+    total: number;
+}
 /**
  * Thin HTTP client for the threadctx cloud API. Talks to either the
  * hosted threadctx.dev service or a self-hosted deployment (set
@@ -19,7 +30,14 @@ export declare class CloudClient {
     private apiKey;
     private actorId?;
     constructor(apiUrl: string, apiKey: string, actorId?: string | undefined);
+    private authHeaders;
     private request;
     write(repo: string, content: string, tags: string[]): Promise<CloudWriteResponse>;
     query(repo: string, taskDescription: string, maxResults: number): Promise<CloudQueryResponse>;
+    /**
+     * Most-recent memories for a repo, used by `threadctx capture` to dedup new
+     * extractions against what's already stored. Best-effort: on any error (e.g. an
+     * older server without the list endpoint) it returns [] so capture still runs.
+     */
+    recent(repo: string, limit?: number): Promise<CloudMemory[]>;
 }

package/dist/cloud-client.js

@@ -12,7 +12,7 @@ export class CloudClient {
         this.apiKey = apiKey;
         this.actorId = actorId;
     }
-    async request(path, body) {
+    authHeaders() {
         const headers = {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${this.apiKey}`,
@@ -20,9 +20,12 @@ export class CloudClient {
         // Anonymous per-developer id for seat accounting (see config.resolveActorId).
         if (this.actorId)
             headers['X-Threadctx-Actor'] = this.actorId;
+        return headers;
+    }
+    async request(path, body) {
         const res = await fetch(`${this.apiUrl}${path}`, {
             method: 'POST',
-            headers,
+            headers: this.authHeaders(),
             body: JSON.stringify(body),
         });
         if (!res.ok) {
@@ -47,4 +50,22 @@ export class CloudClient {
             max_results: maxResults,
         });
     }
+    /**
+     * Most-recent memories for a repo, used by `threadctx capture` to dedup new
+     * extractions against what's already stored. Best-effort: on any error (e.g. an
+     * older server without the list endpoint) it returns [] so capture still runs.
+     */
+    async recent(repo, limit = 100) {
+        try {
+            const url = `${this.apiUrl}/memory/list?repo=${encodeURIComponent(repo)}&limit=${limit}`;
+            const res = await fetch(url, { method: 'GET', headers: this.authHeaders() });
+            if (!res.ok)
+                return [];
+            const json = (await res.json());
+            return json.memories ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
 }

package/dist/llm.d.ts

@@ -0,0 +1,20 @@
+export type ProviderName = 'anthropic' | 'openai';
+export interface LlmProvider {
+    name: ProviderName;
+    apiKey: string;
+    model: string;
+}
+/**
+ * Pick a provider from the environment. Explicit provider via
+ * THREADCTX_CAPTURE_PROVIDER wins; otherwise Anthropic is preferred when both
+ * keys are present. Returns null when no usable key is configured.
+ */
+export declare function detectProvider(explicitModel?: string): LlmProvider | null;
+/** Send a system+user prompt and return the model's raw text response. */
+export declare function complete(provider: LlmProvider, system: string, user: string): Promise<string>;
+/**
+ * Parse the first top-level JSON array out of a model response, tolerating
+ * ```json fences and surrounding prose. Returns [] if nothing parseable is found
+ * rather than throwing, so a chatty model can never crash a capture run.
+ */
+export declare function parseJsonArray(text: string): unknown[];

package/dist/llm.js

@@ -0,0 +1,109 @@
+// Minimal, dependency-free LLM client used by `threadctx capture` to distill
+// git history into memories. Deliberately uses each provider's raw HTTP API via
+// global fetch (Node 18+) rather than an SDK, to keep the `npx threadctx-mcp`
+// install a single small package with no transitive AI-SDK weight.
+//
+// The key is the *user's own* provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY),
+// read from the environment — capture never routes text through threadctx's
+// servers, so local mode still makes no network call beyond the LLM provider the
+// user already trusts with their code.
+const DEFAULT_MODELS = {
+    // Small, fast, cheap models — extraction is a cheap classification-ish task and
+    // capture may run over many commits, so we default low-cost and let --model or
+    // THREADCTX_CAPTURE_MODEL override for higher-fidelity runs.
+    anthropic: 'claude-haiku-4-5-20251001',
+    openai: 'gpt-4o-mini',
+};
+/**
+ * Pick a provider from the environment. Explicit provider via
+ * THREADCTX_CAPTURE_PROVIDER wins; otherwise Anthropic is preferred when both
+ * keys are present. Returns null when no usable key is configured.
+ */
+export function detectProvider(explicitModel) {
+    const forced = process.env.THREADCTX_CAPTURE_PROVIDER;
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    const model = explicitModel || process.env.THREADCTX_CAPTURE_MODEL;
+    const build = (name, apiKey) => ({
+        name,
+        apiKey,
+        model: model || DEFAULT_MODELS[name],
+    });
+    if (forced === 'anthropic' && anthropicKey)
+        return build('anthropic', anthropicKey);
+    if (forced === 'openai' && openaiKey)
+        return build('openai', openaiKey);
+    if (anthropicKey)
+        return build('anthropic', anthropicKey);
+    if (openaiKey)
+        return build('openai', openaiKey);
+    return null;
+}
+/** Send a system+user prompt and return the model's raw text response. */
+export async function complete(provider, system, user) {
+    return provider.name === 'anthropic'
+        ? completeAnthropic(provider, system, user)
+        : completeOpenai(provider, system, user);
+}
+async function completeAnthropic(provider, system, user) {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': provider.apiKey,
+            'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+            model: provider.model,
+            max_tokens: 2048,
+            system,
+            messages: [{ role: 'user', content: user }],
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Anthropic API error (${res.status}): ${await res.text().catch(() => '')}`);
+    const json = (await res.json());
+    return (json.content ?? [])
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text ?? '')
+        .join('');
+}
+async function completeOpenai(provider, system, user) {
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${provider.apiKey}`,
+        },
+        body: JSON.stringify({
+            model: provider.model,
+            messages: [
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ],
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`OpenAI API error (${res.status}): ${await res.text().catch(() => '')}`);
+    const json = (await res.json());
+    return json.choices?.[0]?.message?.content ?? '';
+}
+/**
+ * Parse the first top-level JSON array out of a model response, tolerating
+ * ```json fences and surrounding prose. Returns [] if nothing parseable is found
+ * rather than throwing, so a chatty model can never crash a capture run.
+ */
+export function parseJsonArray(text) {
+    const cleaned = text.replace(/```(?:json)?/gi, '').trim();
+    const start = cleaned.indexOf('[');
+    const end = cleaned.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return [];
+    try {
+        const parsed = JSON.parse(cleaned.slice(start, end + 1));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/rules.d.ts

@@ -0,0 +1,16 @@
+export declare const RULES_BODY: string;
+export type RuleResult = 'created' | 'updated' | 'unchanged';
+export interface AppliedRule {
+    key: string;
+    label: string;
+    result: RuleResult;
+}
+/**
+ * Idempotently ensure every applicable agent's project rules contain the "check
+ * team memory" instruction. Universal files (AGENTS.md, CLAUDE.md) and Cursor
+ * are always written; tool-specific files (Copilot, Windsurf, Cline, Gemini) are
+ * written only when that tool's footprint is detected in the repo, so we never
+ * scatter rule files for tools the team doesn't use. Safe to call on every
+ * server start — repeat calls are no-ops once each file is already current.
+ */
+export declare function applyRules(projectRoot: string): AppliedRule[];

package/dist/rules.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// The exact instruction dropped into an agent's project rules. MCP is
+// pull-based — the model only calls memory_query/memory_write if something
+// tells it to — so this is the highest-leverage thing for making the memory
+// actually get read. Also sent verbatim as the MCP `initialize` response's
+// `instructions` field (see server.ts) so it reaches every client even
+// before any file gets written.
+export const RULES_BODY = [
+    '## Team memory (threadctx)',
+    '',
+    '- **Before** starting any non-trivial task, call `memory_query` with a short',
+    '  description of what you are about to do. Check for prior decisions, fixes,',
+    '  and gotchas on this repo before writing code — not after.',
+    '- **After** resolving a non-obvious bug, making an architectural decision, or',
+    '  learning something that would save a teammate time, call `memory_write` to',
+    '  save it. Write it so a future reader has full context.',
+].join('\n');
+const MARKER_START = '<!-- threadctx:start (managed — edit above/below, not between) -->';
+const MARKER_END = '<!-- threadctx:end -->';
+// The marker-fenced block, shared by every target. For "shared" files we splice
+// just this block in and leave the rest of the file alone; for "dedicated" files
+// (ones whose filename is ours) the whole file is this block, optionally under a
+// tool-specific frontmatter header.
+const managedBlock = `${MARKER_START}\n${RULES_BODY}\n${MARKER_END}\n`;
+/**
+ * Insert (or refresh) the threadctx rules block in a shared, general-purpose
+ * rules file (CLAUDE.md, AGENTS.md, Copilot/Gemini instructions), idempotently.
+ * Creates the file if missing, preserves any of the user's own content outside
+ * the marker-fenced block.
+ */
+function upsertMarkedBlock(filePath) {
+    if (!existsSync(filePath)) {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, managedBlock);
+        return 'created';
+    }
+    const existing = readFileSync(filePath, 'utf-8');
+    const startIdx = existing.indexOf(MARKER_START);
+    if (startIdx !== -1) {
+        const endIdx = existing.indexOf(MARKER_END, startIdx);
+        if (endIdx !== -1) {
+            const before = existing.slice(0, startIdx);
+            const after = existing.slice(endIdx + MARKER_END.length);
+            const next = `${before}${managedBlock.trimEnd()}${after}`;
+            if (next === existing)
+                return 'unchanged';
+            writeFileSync(filePath, next);
+            return 'updated';
+        }
+    }
+    // No managed block yet — append one, keeping the user's existing content.
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(filePath, `${existing}${sep}${managedBlock}`);
+    return 'updated';
+}
+/**
+ * Insert (or refresh) a dedicated rule file whose entire contents we own (e.g.
+ * .cursor/rules/threadctx.mdc). Because the filename is ours alone, on a
+ * mismatch we simply rewrite it in full rather than doing marker surgery.
+ * `frontmatter` lines (if any) are written above the managed block — some tools
+ * require a small YAML header to mark a rule as always-active.
+ */
+function upsertDedicatedFile(filePath, frontmatter) {
+    const header = frontmatter.length ? `---\n${frontmatter.join('\n')}\n---\n\n` : '';
+    const content = `${header}${managedBlock}`;
+    if (!existsSync(filePath)) {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content);
+        return 'created';
+    }
+    if (readFileSync(filePath, 'utf-8') === content)
+        return 'unchanged';
+    writeFileSync(filePath, content);
+    return 'updated';
+}
+const dirExists = (root, ...segs) => existsSync(join(root, ...segs));
+const pathExists = (root, ...segs) => existsSync(join(root, ...segs));
+const TARGETS = [
+    // --- Universal: always written, broad coverage, low noise ---
+    {
+        key: 'agents',
+        label: 'AGENTS.md',
+        relPath: ['AGENTS.md'],
+        kind: 'shared',
+    },
+    {
+        key: 'claude',
+        label: 'CLAUDE.md',
+        relPath: ['CLAUDE.md'],
+        kind: 'shared',
+    },
+    {
+        // Kept always-on (not footprint-gated) to preserve prior behavior: Cursor is
+        // a primary target and its global-MCP users may not have a project .cursor/.
+        key: 'cursor',
+        label: '.cursor/rules/threadctx.mdc',
+        relPath: ['.cursor', 'rules', 'threadctx.mdc'],
+        kind: 'dedicated',
+        frontmatter: ['description: Use threadctx shared team memory', 'alwaysApply: true'],
+    },
+    // --- Footprint-detected: only written when the tool is clearly in use ---
+    {
+        key: 'copilot',
+        label: '.github/copilot-instructions.md',
+        relPath: ['.github', 'copilot-instructions.md'],
+        kind: 'shared',
+        detect: (root) => dirExists(root, '.github'),
+    },
+    {
+        key: 'windsurf',
+        label: '.windsurf/rules/threadctx.md',
+        relPath: ['.windsurf', 'rules', 'threadctx.md'],
+        kind: 'dedicated',
+        frontmatter: ['trigger: always_on', 'description: Use threadctx shared team memory'],
+        detect: (root) => dirExists(root, '.windsurf'),
+    },
+    {
+        // Cline doesn't read AGENTS.md, so this file is the only way it ever sees the
+        // instruction. Cline accepts either a .clinerules file or a .clinerules/ dir.
+        key: 'cline',
+        label: '.clinerules/threadctx.md',
+        relPath: ['.clinerules', 'threadctx.md'],
+        kind: 'dedicated',
+        detect: (root) => pathExists(root, '.clinerules'),
+    },
+    {
+        // Gemini CLI uses its own GEMINI.md (doesn't read AGENTS.md).
+        key: 'gemini',
+        label: 'GEMINI.md',
+        relPath: ['GEMINI.md'],
+        kind: 'shared',
+        detect: (root) => dirExists(root, '.gemini'),
+    },
+];
+function applyTarget(projectRoot, t) {
+    const filePath = join(projectRoot, ...t.relPath);
+    return t.kind === 'shared'
+        ? upsertMarkedBlock(filePath)
+        : upsertDedicatedFile(filePath, t.frontmatter ?? []);
+}
+/**
+ * Idempotently ensure every applicable agent's project rules contain the "check
+ * team memory" instruction. Universal files (AGENTS.md, CLAUDE.md) and Cursor
+ * are always written; tool-specific files (Copilot, Windsurf, Cline, Gemini) are
+ * written only when that tool's footprint is detected in the repo, so we never
+ * scatter rule files for tools the team doesn't use. Safe to call on every
+ * server start — repeat calls are no-ops once each file is already current.
+ */
+export function applyRules(projectRoot) {
+    const applied = [];
+    for (const t of TARGETS) {
+        if (t.detect && !t.detect(projectRoot))
+            continue;
+        applied.push({ key: t.key, label: t.label, result: applyTarget(projectRoot, t) });
+    }
+    return applied;
+}

package/dist/server.js

@@ -7,6 +7,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { loadConfig } from './config.js';
 import { LocalStore } from './local-store.js';
 import { CloudClient } from './cloud-client.js';
+import { applyRules, RULES_BODY } from './rules.js';
 // Consistent attribution string across every surface (Claude Code terminal
 // output, Cursor's agent panel, future surfaces). See spec section 2.4 —
 // the same short string everywhere is what makes the brand legible.
@@ -44,7 +45,34 @@ export async function startServer() {
     const localStore = useCloud ? null : new LocalStore(config.dbPath);
     const cloudClient = useCloud ? new CloudClient(config.apiUrl, config.apiKey, config.actorId) : null;
     const repo = config.repo;
-    const server = new Server({ name: 'threadctx', version: packageVersion }, { capabilities: { tools: {} } });
+    // Reliably getting memory_query/memory_write actually *used* is the whole
+    // product, so this doesn't wait for a human to run `threadctx init` — it
+    // happens on every server start, idempotently (a no-op once both files are
+    // already current). Never let a file-permission hiccup here take down the
+    // server; opt out entirely with THREADCTX_NO_AUTO_RULES=1.
+    if (!process.env.THREADCTX_NO_AUTO_RULES) {
+        try {
+            const touched = applyRules(process.cwd()).filter((r) => r.result !== 'unchanged');
+            if (touched.length > 0) {
+                console.error('[threadctx] Added team-memory instructions to your project rules ' +
+                    `(${touched.map((r) => r.label).join(', ')}) ` +
+                    '— your agent will check shared memory automatically from now on.');
+            }
+        }
+        catch (err) {
+            console.error('[threadctx] Could not write project rules (non-fatal):', err);
+        }
+    }
+    const server = new Server({ name: 'threadctx', version: packageVersion }, {
+        capabilities: { tools: {} },
+        // Sent to every MCP client on the `initialize` handshake, so the
+        // "check memory before/after" guidance reaches the model even for
+        // clients that don't read CLAUDE.md/.cursor/rules, and even before any
+        // file gets written. Belt-and-suspenders with the file-based rules
+        // above — client-side handling of this field isn't guaranteed uniform
+        // across every MCP client, so we don't rely on it alone.
+        instructions: RULES_BODY,
+    });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadctx-mcp",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "mcpName": "io.github.threadctx-dev/threadctx-mcp",
   "description": "Shared memory MCP server for AI coding agents. Local-only by default; point it at threadctx.dev (or your own deployment) to share memory across your team.",
   "type": "module",
@@ -13,7 +13,7 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx watch src/cli.ts",
     "start": "node dist/cli.js",
-    "test": "npm run build && node test/smoke.mjs",
+    "test": "npm run build && node test/rules.test.mjs && node test/capture.test.mjs && node test/smoke.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {