fathom-mcp 0.4.1 → 0.4.3

package/README.md

@@ -70,7 +70,7 @@ npx fathom-mcp status        # Check server connection + workspace status
 | `fathom_vault_vsearch` | Semantic/vector search |
 | `fathom_vault_query` | Hybrid search (BM25 + vectors + reranking) |
 | `fathom_room_post` | Post to a shared room (supports @mentions) |
-| `fathom_room_read` | Read recent room messages |
+| `fathom_room_read` | Read room messages (windowed, anchored to latest; `minutes`/`start` for pagination) |
 | `fathom_room_list` | List all rooms |
 | `fathom_room_describe` | Set a room's description/topic |
 | `fathom_workspaces` | List all configured workspaces |

package/fathom-agents.md

@@ -2,34 +2,9 @@
 
 {{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.
+Local files live in `{{VAULT_DIR}}/`. The vault is for long-form content — things that need to breathe, not be queried.
 
 **Folder conventions:**
 - `research/` — reading notes, paper annotations, deep dives
@@ -50,7 +25,6 @@ status: draft           # optional: draft | published | archived
 
 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="..."`
@@ -63,6 +37,5 @@ Your sender identity is automatic — messages are tagged with `{{WORKSPACE_NAME
 
 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
+3. Session heartbeats → `vault/daily/`
+4. When done — write what you found and what questions remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {

package/scripts/fathom-precompact.sh

@@ -6,6 +6,9 @@
 
 set -euo pipefail
 
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+TOAST="$HOOK_DIR/fathom-toast.sh"
+
 # Walk up to find .fathom.json
 find_config() {
   local dir="$PWD"
@@ -30,18 +33,29 @@ if [ "$HOOK_ENABLED" != "True" ] && [ "$HOOK_ENABLED" != "true" ]; then
   exit 0
 fi
 
+# Toast: start multi-stage
+"$TOAST" memento --status precompact &>/dev/null
+"$TOAST" --update precompact "⏳ Getting context..." &>/dev/null
+
 # Read PreCompact input (contains transcript_path)
 INPUT=$(cat)
 TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('transcript_path',''))" 2>/dev/null || echo "")
 
 if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  "$TOAST" --update precompact "✗ No transcript found" &>/dev/null
+  "$TOAST" --close precompact &>/dev/null &
   exit 0
 fi
 
+# Toast: extracting
+"$TOAST" --update precompact "⏳ Extracting memories..." &>/dev/null
+
 # Extract vault file paths from transcript
 VAULT_FILES=$(grep -oP 'vault/[a-zA-Z0-9_/.-]+\.md' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || echo "")
 
 if [ -z "$VAULT_FILES" ]; then
+  "$TOAST" --update precompact "✓ No vault files to record" &>/dev/null
+  ("$TOAST" --close precompact &>/dev/null &)
   exit 0
 fi
 
@@ -59,6 +73,11 @@ done
 
 # Output summary
 FILE_COUNT=$(echo "$VAULT_FILES" | wc -l)
+
+# Toast: done
+"$TOAST" --update precompact "✓ Stored ${FILE_COUNT} vault file(s)" &>/dev/null
+("$TOAST" --close precompact &>/dev/null &)
+
 python3 -c "
 import json, sys
 result = {

package/scripts/fathom-recall.sh

@@ -11,6 +11,7 @@
 set -o pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+TOAST="$HOOK_DIR/fathom-toast.sh"
 VSEARCH_CACHE="/tmp/fathom-vsearch-cache.json"
 VSEARCH_LOCK="/tmp/fathom-vsearch.lock"
 STALE_LOCK_SECONDS=180   # 3 minutes — lock older than this is considered stale
@@ -75,6 +76,9 @@ fi
 
 QUERY="${USER_MESSAGE:0:500}"
 
+# Toast: start retrieving
+"$TOAST" fathom "⏳ Retrieving docs..." &>/dev/null
+
 # --- Phase 1: Read cached vsearch results from previous query ---
 CACHED_VSEARCH=""
 if [ -f "$VSEARCH_CACHE" ]; then
@@ -151,6 +155,10 @@ if [ -n "$BM25_RESULTS" ] || [ -n "$CACHED_VSEARCH" ]; then
     fi
 
     SUMMARY="Fathom Vault: ${VAULT_COUNT} memories"
+
+    # Toast: result
+    "$TOAST" fathom "✓ ${VAULT_COUNT} docs recalled" &>/dev/null
+
     python3 -c "
 import json, sys
 summary = sys.argv[1]
@@ -163,6 +171,9 @@ print(json.dumps({
     }
 }))
 " "$SUMMARY" "$DETAIL_TEXT"
+else
+    # Toast: no results
+    "$TOAST" fathom "✓ No docs matched" &>/dev/null
 fi
 
 # --- Phase 3: Launch background vsearch for current query ---

package/scripts/fathom-toast.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# fathom-toast.sh — tmux popup notifications for Fathom/Memento hooks.
+#
+# Usage:
+#   fathom-toast.sh <system> <message>          # one-shot toast (auto-closes after 2s)
+#   fathom-toast.sh <system> --status <id>      # start a multi-stage toast (poll mode)
+#   fathom-toast.sh --update <id> <message>     # update a running toast
+#   fathom-toast.sh --close <id>                # close a running toast (after delay)
+#
+# Systems: fathom, memento
+#   fathom  → 📝 purple (colour141)
+#   memento → 🧠 teal (colour37)
+#
+# Multi-stage example (PreCompact):
+#   fathom-toast.sh memento --status precompact
+#   fathom-toast.sh --update precompact "⏳ Getting context..."
+#   fathom-toast.sh --update precompact "⏳ Extracting memories..."
+#   fathom-toast.sh --update precompact "✓ Stored 7 memories"
+#   fathom-toast.sh --close precompact
+
+TOAST_DIR="/tmp/fathom-toast"
+mkdir -p "$TOAST_DIR"
+
+# Bail silently if not in tmux
+if ! tmux info &>/dev/null; then
+    exit 0
+fi
+
+get_style() {
+    local system="$1"
+    case "$system" in
+        memento) echo "colour37" ;;
+        fathom)  echo "colour141" ;;
+        *)       echo "colour245" ;;
+    esac
+}
+
+get_icon() {
+    local system="$1"
+    case "$system" in
+        memento) echo "🧠" ;;
+        fathom)  echo "📝" ;;
+        *)       echo "📌" ;;
+    esac
+}
+
+get_title() {
+    local system="$1"
+    case "$system" in
+        memento) echo "Memento" ;;
+        fathom)  echo "Fathom" ;;
+        *)       echo "$system" ;;
+    esac
+}
+
+# One-shot toast
+toast_oneshot() {
+    local system="$1"
+    local message="$2"
+    local colour icon title
+    colour=$(get_style "$system")
+    icon=$(get_icon "$system")
+    title=$(get_title "$system")
+
+    (tmux display-popup -x R -y 0 -w 42 -h 3 \
+        -s "fg=$colour" -T " $icon $title " -E \
+        "echo '  $message'; sleep 2" &>/dev/null &)
+}
+
+# Start a multi-stage toast (polling status file)
+toast_start() {
+    local system="$1"
+    local id="$2"
+    local status_file="$TOAST_DIR/$id"
+    local colour icon title
+    colour=$(get_style "$system")
+    icon=$(get_icon "$system")
+    title=$(get_title "$system")
+
+    echo "⏳ Starting..." > "$status_file"
+
+    (tmux display-popup -x R -y 0 -w 42 -h 3 \
+        -s "fg=$colour" -T " $icon $title " -E "
+        LAST=''
+        while [ -f '$status_file' ]; do
+            MSG=\$(cat '$status_file' 2>/dev/null)
+            if [ \"\$MSG\" != \"\$LAST\" ]; then
+                clear
+                echo \"  \$MSG\"
+                LAST=\"\$MSG\"
+            fi
+            case \"\$MSG\" in ✓*|✗*) sleep 2; break ;; esac
+            sleep 0.2
+        done
+    " &>/dev/null &)
+}
+
+# Update a running toast
+toast_update() {
+    local id="$1"
+    local message="$2"
+    local status_file="$TOAST_DIR/$id"
+    echo "$message" > "$status_file"
+}
+
+# Close a running toast (remove status file — popup exits on next poll)
+toast_close() {
+    local id="$1"
+    local status_file="$TOAST_DIR/$id"
+    # Give the popup time to display the final message
+    sleep 2
+    rm -f "$status_file"
+}
+
+# --- Argument parsing ---
+case "${1:-}" in
+    --update)
+        toast_update "$2" "$3"
+        ;;
+    --close)
+        toast_close "$2"
+        ;;
+    fathom|memento)
+        SYSTEM="$1"
+        shift
+        if [ "${1:-}" = "--status" ]; then
+            toast_start "$SYSTEM" "$2"
+        else
+            toast_oneshot "$SYSTEM" "$*"
+        fi
+        ;;
+    *)
+        echo "Usage: fathom-toast.sh <fathom|memento> <message>" >&2
+        echo "       fathom-toast.sh <fathom|memento> --status <id>" >&2
+        echo "       fathom-toast.sh --update <id> <message>" >&2
+        echo "       fathom-toast.sh --close <id>" >&2
+        exit 1
+        ;;
+esac

package/src/index.js

@@ -220,13 +220,17 @@ const tools = [
   {
     name: "fathom_room_read",
     description:
-      "Read recent messages from a shared room. Returns messages from the last N hours " +
-      "(default 24). Use during orient phase to catch up on cross-workspace conversation.",
+      "Read recent messages from a shared room. Returns messages within a time window anchored " +
+      "to the latest message. Default: 60 minutes before the latest message. Use start to look " +
+      "further back. Example: minutes=15, start=120 returns 15 minutes of conversation starting " +
+      "2 hours before the latest message. Response includes window metadata with has_older flag " +
+      "for pseudo-pagination.",
     inputSchema: {
       type: "object",
       properties: {
         room: { type: "string", description: "Room name to read from" },
-        hours: { type: "number", description: "How many hours of history to return. Default: 24." },
+        minutes: { type: "number", description: "Window duration in minutes. Default: 60." },
+        start: { type: "number", description: "Offset in minutes from the latest message. Default: 0 (window ends at latest message). Set to 120 to look back starting 2 hours before the latest message." },
       },
       required: ["room"],
     },
@@ -412,7 +416,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await client.roomPost(args.room, args.message, config.workspace);
       break;
     case "fathom_room_read":
-      result = await client.roomRead(args.room, args.hours);
+      result = await client.roomRead(args.room, args.minutes, args.start);
       break;
     case "fathom_room_list":
       result = await client.roomList();

package/src/server-client.js

@@ -82,9 +82,9 @@ export function createClient(config) {
     });
   }
 
-  async function roomRead(room, hours) {
+  async function roomRead(room, minutes, start) {
     return request("GET", `/api/room/${encodeURIComponent(room)}`, {
-      params: { hours },
+      params: { minutes, start },
     });
   }