fathom-mcp 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,8 +5,9 @@
 Multi-agent support.
 
 - **Multi-agent init wizard** — auto-detects installed agents and generates per-agent MCP configs
-- **Supported agents:** Claude Code, OpenAI Codex, Gemini CLI, Cursor, VS Code Copilot, Windsurf
-- **Per-agent config writers** — `.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `~/.codeium/windsurf/mcp_config.json`
+- **Supported agents:** Claude Code, OpenAI Codex, Gemini CLI, OpenCode
+- **Per-agent config writers** — `.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`, `opencode.json`
+- **Agent instructions boilerplate** — `fathom-agents.md` template for memory discipline, vault conventions, cross-workspace communication
 - **Conditional hooks** — hook setup only for Claude Code (other agents don't support hooks)
 - **`agents` array** replaces legacy `architecture` string in `.fathom.json` — backward compatible
 - **Server-side agent dispatch** — persistent sessions launch the correct agent CLI per workspace

package/README.md

@@ -18,9 +18,7 @@ MCP server for [Fathom](https://hifathom.com) — vault operations, search, room
 | **Claude Code** | `.mcp.json` | `.claude/` directory |
 | **OpenAI Codex** | `.codex/config.toml` | `.codex/` directory |
 | **Gemini CLI** | `.gemini/settings.json` | `.gemini/` directory |
-| **Cursor** | `.cursor/mcp.json` | `.cursor/` directory |
-| **VS Code Copilot** | `.vscode/mcp.json` | `.vscode/` directory |
-| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | `~/.codeium/windsurf/` directory |
+| **OpenCode** | `opencode.json` | `opencode.json` file |
 
 The init wizard auto-detects which agents you have and generates the right config for each.
 

package/fathom-agents.md

@@ -0,0 +1,68 @@
+# {{WORKSPACE_NAME}}
+
+{{DESCRIPTION}}
+
+## Memory — Memento Protocol
+
+Working memory is managed by Memento (workspace: `{{WORKSPACE_NAME}}`).
+
+**On session start:**
+1. `memento_health` — verify connection
+2. `memento_item_list` — check active work items and their next actions
+3. `memento_recall` with current task context — find relevant past memories
+
+**During work — actively manage your memories:**
+- `memento_store` when you learn something, make a decision, or discover a pattern
+- `memento_recall` before starting any subtask — someone may have already figured it out
+- `memento_item_update` as you make progress — don't wait until the end
+- `memento_item_create` when new work emerges
+- `memento_skip_add` the moment you hit a dead end (with expiry)
+- `memento_consolidate` when recall returns 3+ overlapping memories on the same topic
+- Delete or archive items that are done or wrong — stale memory is worse than no memory
+
+**Writing discipline — instructions, not logs:**
+- Write: "API moved to /v2 — update all calls" not "checked API, got 404"
+- Write: "Skip X until condition Y" not "checked X, it was quiet"
+- Tag generously — tags power recall and consolidation
+- Set expiration on time-sensitive facts
+- The test: could a future you, with zero context, read this and know exactly what to do?
+
+## Vault
+
+Local files live in `{{VAULT_DIR}}/`. Vault is for long-form content — things that need to breathe, not be queried. Decisions and next-actions go in Memento; reflections, research notes, and finished pieces go in the vault.
+
+**Folder conventions:**
+- `research/` — reading notes, paper annotations, deep dives
+- `thinking/` — speculative connections, insights, one file per idea
+- `daily/` — session heartbeats and progress logs
+
+**Frontmatter required** on vault files:
+```yaml
+---
+title: My Note          # required (string)
+date: 2026-02-26        # required (YYYY-MM-DD)
+tags: [research, topic] # optional
+status: draft           # optional: draft | published | archived
+---
+```
+
+## Cross-Workspace Communication
+
+This workspace is part of a multi-workspace system. Other workspaces exist — you can talk to them.
+
+- **Peek at another workspace's memory:** `memento_recall query="..." workspace="other-ws"`
+- **Peek at another workspace's vault:** `fathom_vault_read path="file.md" workspace="other-ws"`
+- **Send a direct message:** `fathom_send workspace="other-ws" message="..."`
+- **Post to a shared room:** `fathom_room_post room="general" message="..."`
+- **Read room history:** `fathom_room_read room="general"`
+- **Discover workspaces:** `fathom_workspaces`
+
+Your sender identity is automatic — messages are tagged with `{{WORKSPACE_NAME}}`.
+
+## Workflow
+
+1. Research and reading notes → `vault/research/`
+2. Speculative connections and insights → `vault/thinking/`
+3. Key findings and decisions → `memento_store` with tags
+4. Session heartbeats → `vault/daily/`
+5. When done — update Memento items, write what you found and what questions remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "src/",
     "scripts/",
+    "fathom-agents.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -39,9 +40,7 @@
     "claude",
     "codex",
     "gemini",
-    "cursor",
-    "copilot",
-    "windsurf",
+    "opencode",
     "ai-agent",
     "memory"
   ]

package/src/cli.js

@@ -10,7 +10,6 @@
  */
 
 import fs from "fs";
-import os from "os";
 import path from "path";
 import readline from "readline";
 import { fileURLToPath } from "url";
@@ -157,42 +156,20 @@ function writeGeminiJson(cwd) {
   return ".gemini/settings.json";
 }
 
-function writeCursorJson(cwd) {
-  const dir = path.join(cwd, ".cursor");
-  fs.mkdirSync(dir, { recursive: true });
-  const filePath = path.join(dir, "mcp.json");
-  const existing = readJsonFile(filePath) || {};
-  deepMerge(existing, { mcpServers: { "fathom-vault": MCP_SERVER_ENTRY } });
-  writeJsonFile(filePath, existing);
-  return ".cursor/mcp.json";
-}
-
-function writeVscodeJson(cwd) {
-  const dir = path.join(cwd, ".vscode");
-  fs.mkdirSync(dir, { recursive: true });
-  const filePath = path.join(dir, "mcp.json");
+function writeOpencodeJson(cwd) {
+  const filePath = path.join(cwd, "opencode.json");
   const existing = readJsonFile(filePath) || {};
   deepMerge(existing, {
-    servers: {
+    mcp: {
       "fathom-vault": {
-        type: "stdio",
-        command: "npx",
-        args: ["-y", "fathom-mcp"],
+        type: "local",
+        command: ["npx", "-y", "fathom-mcp"],
+        enabled: true,
       },
     },
   });
   writeJsonFile(filePath, existing);
-  return ".vscode/mcp.json";
-}
-
-function writeWindsurfJson(_cwd) {
-  const dir = path.join(os.homedir(), ".codeium", "windsurf");
-  fs.mkdirSync(dir, { recursive: true });
-  const filePath = path.join(dir, "mcp_config.json");
-  const existing = readJsonFile(filePath) || {};
-  deepMerge(existing, { mcpServers: { "fathom-vault": MCP_SERVER_ENTRY } });
-  writeJsonFile(filePath, existing);
-  return "~/.codeium/windsurf/mcp_config.json";
+  return "opencode.json";
 }
 
 const AGENTS = {
@@ -217,31 +194,17 @@ const AGENTS = {
     hasHooks: false,
     nextSteps: "Run `gemini` in this directory — fathom tools load automatically.",
   },
-  "cursor": {
-    name: "Cursor",
-    detect: (cwd) => fs.existsSync(path.join(cwd, ".cursor")),
-    configWriter: writeCursorJson,
-    hasHooks: false,
-    nextSteps: "Restart Cursor — fathom tools appear in MCP settings.",
-  },
-  "vscode": {
-    name: "VS Code Copilot",
-    detect: (cwd) => fs.existsSync(path.join(cwd, ".vscode")),
-    configWriter: writeVscodeJson,
+  "opencode": {
+    name: "OpenCode",
+    detect: (cwd) => fs.existsSync(path.join(cwd, "opencode.json")),
+    configWriter: writeOpencodeJson,
     hasHooks: false,
-    nextSteps: "Reload VS Code — fathom tools appear in Copilot.",
-  },
-  "windsurf": {
-    name: "Windsurf",
-    detect: () => fs.existsSync(path.join(os.homedir(), ".codeium", "windsurf")),
-    configWriter: writeWindsurfJson,
-    hasHooks: false,
-    nextSteps: "Restart Windsurf — fathom tools appear in Cascade.",
+    nextSteps: "Run `opencode` in this directory — fathom tools load automatically.",
   },
 };
 
 // Exported for testing
-export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeCursorJson, writeVscodeJson, writeWindsurfJson };
+export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeOpencodeJson };
 
 // --- Init wizard -------------------------------------------------------------
 
@@ -371,6 +334,20 @@ async function runInit() {
     console.log(`  · ${vault}/ (already exists)`);
   }
 
+  // fathom-agents.md — boilerplate agent instructions
+  const agentMdSrc = path.join(__dirname, "..", "fathom-agents.md");
+  const agentMdDest = path.join(cwd, ".fathom", "fathom-agents.md");
+  try {
+    let template = fs.readFileSync(agentMdSrc, "utf-8");
+    template = template
+      .replace(/\{\{WORKSPACE_NAME\}\}/g, workspace)
+      .replace(/\{\{VAULT_DIR\}\}/g, vault)
+      .replace(/\{\{DESCRIPTION\}\}/g, description || `${workspace} workspace`);
+    fs.mkdirSync(path.dirname(agentMdDest), { recursive: true });
+    fs.writeFileSync(agentMdDest, template);
+    console.log("  ✓ .fathom/fathom-agents.md");
+  } catch { /* template not found — skip silently */ }
+
   // Per-agent config files
   for (const agentKey of selectedAgents) {
     const agent = AGENTS[agentKey];
@@ -450,7 +427,15 @@ async function runInit() {
     const agent = AGENTS[agentKey];
     console.log(`    · ${agent.name}: ${agent.nextSteps}`);
   }
-  console.log();
+  console.log(`
+  Agent instructions:
+    Some instructions are needed for your agent to use Fathom + Memento
+    effectively (memory discipline, vault conventions, cross-workspace
+    communication). Saved to: .fathom/fathom-agents.md
+
+    Paste it into your CLAUDE.md, AGENTS.md, or equivalent — or point
+    your agent at the file and ask it to integrate the instructions.
+`);
 }
 
 // --- Status command ----------------------------------------------------------