threadctx-mcp 0.1.2 → 0.2.0

package/README.md

@@ -6,12 +6,13 @@ per-client integration work.
 
 ## Modes
 
-- **Local (default, free, no signup):** memory stored in SQLite at
-  `~/.threadctx/local.json` — **zero native dependencies**, so
+- **Local (default, free, no signup):** memory stored as a plain JSON file
+  at `~/.threadctx/local.json` — **zero native dependencies**, so
   `npx threadctx-mcp` installs instantly on any machine with Node 18+ (no
   compiler, no node-gyp step). No network calls except to whichever LLM
   provider your agent already uses. Matching is keyword-based, scoped to
-  the current repo (detected via `git remote`).
+  the current repo (detected via `git remote`). Run `npx threadctx-mcp list`
+  any time to see exactly what your agents have stored.
 - **Cloud (paid Team tier+):** memory shared across everyone on the repo,
   with real semantic search. Requires an API key from
   [threadctx.dev](https://threadctx.dev) (or your own self-hosted
@@ -23,16 +24,30 @@ per-client integration work.
 # Local mode — nothing to configure
 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.
+npx threadctx-mcp init
+
 # Cloud mode — prints the exact MCP config block to paste
 npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx
+
+# See what your agents have written to this machine
+npx threadctx-mcp list            # this repo
+npx threadctx-mcp list --all      # every repo
 ```
 
-This writes a `.threadctx.json` file (just `{ "mode": "cloud" }`) to the
+`init` writes a `.threadctx.json` file (just `{ "mode": "cloud" }`) to the
 current directory. It is safe to commit — it never contains your API key.
 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.
+
 ## Claude Code setup
 
 Add to your Claude Code MCP config (`claude mcp add` or edit
@@ -107,4 +122,15 @@ npm run build   # compiles to dist/ for publishing
 
 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.
+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`.
+
+## 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 list [--all] [--full] [--json]` | Shows what's stored in the local on-disk memory. |

package/dist/cli.js

@@ -1,17 +1,71 @@
 #!/usr/bin/env node
-import { writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { loadConfig } from './config.js';
+import { LocalStore } from './local-store.js';
 import { startServer } from './server.js';
 const [, , command, ...rest] = process.argv;
 function parseFlags(args) {
     const flags = {};
     for (const arg of args) {
-        const match = arg.match(/^--([^=]+)=(.*)$/);
-        if (match)
-            flags[match[1]] = match[2];
+        const kv = arg.match(/^--([^=]+)=(.*)$/);
+        if (kv) {
+            flags[kv[1]] = kv[2];
+            continue;
+        }
+        const bare = arg.match(/^--([^=]+)$/);
+        if (bare)
+            flags[bare[1]] = true;
     }
     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';
@@ -20,9 +74,9 @@ function runInit(args) {
     // at runtime (set it in your MCP client's `env` block). This keeps secrets
     // out of version control by construction.
     const config = { mode };
-    if (mode === 'cloud' && flags['api-url'])
+    if (mode === 'cloud' && typeof flags['api-url'] === 'string')
         config.apiUrl = flags['api-url'];
-    const apiKey = flags['api-key'];
+    const apiKey = typeof flags['api-key'] === 'string' ? flags['api-key'] : undefined;
     if (mode === 'cloud' && !apiKey) {
         console.error('Cloud mode needs an API key. Pass --api-key=<tctx_...> so this command can');
         console.error('show you the exact config block to paste.');
@@ -32,6 +86,16 @@ function runInit(args) {
     const configPath = join(process.cwd(), '.threadctx.json');
     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.
+    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.`);
+        }
+    }
     console.log('');
     if (mode === 'cloud') {
         console.log('Add threadctx to your MCP client config (~/.claude/mcp.json and/or .cursor/mcp.json).');
@@ -54,11 +118,83 @@ function runInit(args) {
         console.log('See the README for the exact block (identical for Claude Code and Cursor).');
     }
 }
+function truncate(text, max) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+/**
+ * A milestone-aware, on-device nudge toward cloud/team mode. Deliberately sends
+ * NOTHING off the machine — it's computed purely from the local store and shown
+ * only in surfaces a human actually reads (`list`). The whole pitch escalates as
+ * the local memory grows, because a large multi-repo store is exactly the point
+ * where "my teammates can't see any of this" becomes a real, felt problem.
+ */
+function cloudNudge(all) {
+    const total = all.length;
+    const repos = new Set(all.map((m) => m.repo)).size;
+    if (repos >= 2 && total >= 5) {
+        return (`↑ You've stored ${total} memories across ${repos} repos on this machine — none of it is\n` +
+            `  visible to your teammates. Share it as team memory: https://threadctx.dev`);
+    }
+    if (total >= 20) {
+        return (`↑ You've built up ${total} local memories — turn them into shared team memory\n` +
+            `  your whole team can query: https://threadctx.dev`);
+    }
+    return 'Local-only memory — share it across your team at https://threadctx.dev';
+}
+/**
+ * `threadctx list` — show what your agents have written to *this machine* in
+ * local mode. Read-only, no network, scoped to the current repo by default
+ * (pass --all to see every repo, --full to print untruncated content, --json
+ * for machine-readable output).
+ */
+function runList(args) {
+    const flags = parseFlags(args);
+    const config = loadConfig();
+    if (config.mode === 'cloud') {
+        console.error('[threadctx] `list` shows the local on-disk store; you are in cloud mode.');
+        console.error('[threadctx] Cloud memories live on the server and are retrieved via memory_query.');
+        console.error('[threadctx] (Set THREADCTX_MODE=local to inspect the local store, if any.)');
+        process.exit(0);
+    }
+    const store = new LocalStore(config.dbPath);
+    const all = store.list();
+    const repoFilter = flags.all === true ? undefined : config.repo;
+    const memories = repoFilter ? all.filter((m) => m.repo === repoFilter) : all;
+    if (flags.json === true) {
+        console.log(JSON.stringify(memories, null, 2));
+        return;
+    }
+    const scope = repoFilter ? `for ${repoFilter}` : 'across all repos';
+    if (memories.length === 0) {
+        console.log(`No local memories ${scope} yet.`);
+        console.log('Your agents write these by calling memory_write. Nothing has been stored here.');
+        if (repoFilter && all.length > 0) {
+            console.log(`(You have ${all.length} in other repos — run with --all to see them.)`);
+        }
+        return;
+    }
+    console.log(`threadctx — ${memories.length} local ${memories.length === 1 ? 'memory' : 'memories'} ${scope}\n`);
+    for (const m of memories) {
+        const date = m.created_at.slice(0, 10);
+        const tags = m.tags.length ? `  [${m.tags.join(', ')}]` : '';
+        const repoTag = repoFilter ? '' : `  ${m.repo}`;
+        console.log(`● ${date}${repoTag}${tags}`);
+        console.log(`  ${flags.full === true ? m.content.trim() : truncate(m.content, 160)}`);
+        console.log(`  id: ${m.id.slice(0, 8)}\n`);
+    }
+    console.log(`Stored at ${config.dbPath}.`);
+    console.log(cloudNudge(all));
+}
 async function main() {
     if (command === 'init') {
         runInit(rest);
         return;
     }
+    if (command === 'list') {
+        runList(rest);
+        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/local-store.d.ts

@@ -5,6 +5,13 @@ export interface LocalMemory {
     created_at: string;
     score: number;
 }
+export interface StoredMemory {
+    id: string;
+    repo: string;
+    content: string;
+    tags: string[];
+    created_at: string;
+}
 /**
  * Local mode storage: a single JSON file on disk, zero network calls,
  * zero accounts, and — deliberately — zero native dependencies.
@@ -27,5 +34,11 @@ export declare class LocalStore {
     private load;
     private persist;
     write(repo: string, content: string, tags: string[]): string;
+    /**
+     * Return stored memories newest-first, optionally scoped to one repo. Used by
+     * the `threadctx list` CLI so a developer can see exactly what their agents
+     * have written to their own machine — no query keywords, no scoring.
+     */
+    list(repo?: string): StoredMemory[];
     query(repo: string, taskDescription: string, maxResults: number): LocalMemory[];
 }

package/dist/local-store.js

@@ -56,6 +56,17 @@ export class LocalStore {
         this.persist();
         return id;
     }
+    /**
+     * Return stored memories newest-first, optionally scoped to one repo. Used by
+     * the `threadctx list` CLI so a developer can see exactly what their agents
+     * have written to their own machine — no query keywords, no scoring.
+     */
+    list(repo) {
+        return this.memories
+            .filter((m) => (repo ? m.repo === repo : true))
+            .slice()
+            .sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
+    }
     query(repo, taskDescription, maxResults) {
         const keywords = taskDescription
             .toLowerCase()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadctx-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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",
   "bin": {