@xultrax-web/agent-memory-mcp 0.8.1 → 0.10.0

package/README.md

@@ -200,6 +200,9 @@ Custom path:
 | `verify_memory`     | Re-evaluate a memory's claims. Extracts URLs/dates/file refs, flags stale-date signals, returns type-specific verification heuristics. Pairs with the `audit_stale` prompt. |
 | `find_backlinks`    | List memories that link to the given memory via `[[wiki-link]]` syntax in their bodies. Useful for "what references this" views.                                            |
 | `find_related`      | Surface memories related to one by combining outbound links, inbound backlinks, shared tags, type match, and content similarity. Navigates the memory graph by association. |
+| `sync_status`       | Report git-sync state: remote URL, branch, uncommitted local files, ahead/behind origin.                                                                                    |
+| `sync_push`         | Commit local memory changes + push to the configured git remote. Auto-timestamps the commit message if none given.                                                          |
+| `sync_pull`         | Fast-forward pull from the git remote. Refuses to pull if local changes are uncommitted.                                                                                    |
 
 ### Prompts
 
@@ -265,8 +268,45 @@ agent-memory save my-mem --type project --description "X" --content "Body" --tag
 agent-memory list --tags "production"          # filter by tag (intersection)
 agent-memory backlinks deploy-process          # memories that link to deploy-process
 agent-memory related deploy-process            # ranked discovery: links + tags + similarity
+agent-memory sync init git@github.com:you/agent-memory.git    # multi-machine setup (one-time)
+agent-memory sync push                         # commit + push local changes
+agent-memory sync pull                         # fast-forward from remote
+agent-memory sync status                       # local + ahead/behind state
+agent-memory ui                                # launch the TUI (browse + edit interactively)
 ```
 
+### Multi-machine memory (git sync)
+
+The killer feature for file-based memory: every dev machine has git, and markdown merges cleanly. `agent-memory sync` turns `.agent-memory/` into a git repo pointed at a (private) remote, and your memories follow you across desktop/laptop/server.
+
+```bash
+# One-time setup
+agent-memory sync init git@github.com:you/agent-memory.git
+
+# End of the day on desktop
+agent-memory sync push
+
+# Pick up your laptop before bed
+agent-memory sync pull
+
+# Save a new memory while reading in bed
+agent-memory save bedtime-thought --type project --description "..." --content "..."
+agent-memory sync push
+
+# Next morning at desktop
+agent-memory sync pull          # picks up the bedtime memory
+```
+
+What's NOT synced (per-machine state, kept local):
+
+- `.lock` — per-process file lock
+- `.events.jsonl` — per-machine audit trail
+- `.trash/` — soft-delete staging
+
+What IS synced: every memory file, the `MEMORY.md` index, and any `.gitignore` you add.
+
+Commits use the identity `agent-memory <agent-memory@local>` by default — set `GIT_AUTHOR_EMAIL` / `GIT_COMMITTER_EMAIL` in your environment if you want per-machine attribution.
+
 ### Audit log + structured logging
 
 Every mutation appends one JSON line to `.agent-memory/.events.jsonl`:
@@ -379,12 +419,33 @@ This server is built to be used daily, not to demo well once.
 - **`find_backlinks`** tool + `agent-memory backlinks <name>` CLI — "what links to this".
 - **`find_related`** tool + `agent-memory related <name>` CLI — combines outbound + inbound links, shared tags, type match, and content similarity into a ranked discovery view.
 
-**Landing in v0.9+:**
+**Shipped in v0.10 · the visual identity (TUI):**
+
+- **`agent-memory ui`** — Ink-based terminal UI for browsing, filtering, searching, and editing memories without leaving the terminal.
+- Type-filter quick-keys (0-4 cycle through all/user/feedback/project/reference)
+- Fuzzy live search with `/`
+- `e` opens the highlighted memory in `$EDITOR` (vim/notepad/nano/whatever) — saves back to disk
+- `d` soft-deletes with `y/n` confirmation
+- Detail pane previews the body of the selected memory
+- Color-coded by type, tag chips inline
+
+**Shipped in v0.9 · the moat — multi-machine memory via git:**
+
+- **`agent-memory sync init <remote-url>`** — convert `.agent-memory/` into a git repo, push to remote.
+- **`agent-memory sync push`** — auto-commit local changes + push.
+- **`agent-memory sync pull`** — fast-forward from remote.
+- **`agent-memory sync status`** — local state + commits ahead/behind origin.
+- **`agent-memory sync log`** — history of cross-machine memory changes.
+- **`sync_status` / `sync_push` / `sync_pull` MCP tools** — the LLM can do this too.
+- Per-machine state (`.lock`, `.events.jsonl`, `.trash/`) auto-excluded from sync.
+- Default commit identity injected (`agent-memory@local`) so machines without `git config --global user.email` work without setup.
+
+**Landing in v0.11+:**
 
 - Folder support (`.agent-memory/work/`, `.agent-memory/personal/`)
-- TUI / web UI for browsing + editing memories in a clean interface
-- `agent-memory sync` for git-backed multi-machine memory (the moat)
 - Memory packs for shareable curated bundles
+- Web UI for browser-based memory browsing (companion to the TUI)
+- Auto-context loading (LLM gets relevant memories transparently before each prompt)
 
 ---
 

package/dist/index.js

@@ -26,9 +26,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import Fuse from "fuse.js";
 import matter from "gray-matter";
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import lockfile from "proper-lockfile";
 // -------------------------------------------------------------
 // Storage location resolution
@@ -42,7 +44,7 @@ function resolveStorageDir() {
     }
     return resolve(process.cwd(), ".agent-memory");
 }
-const MEMORY_DIR = resolveStorageDir();
+export const MEMORY_DIR = resolveStorageDir();
 const INDEX_FILE = join(MEMORY_DIR, "MEMORY.md");
 const TRASH_DIR = join(MEMORY_DIR, ".trash");
 const LOCK_FILE = join(MEMORY_DIR, ".lock");
@@ -177,10 +179,10 @@ const SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,80}$/;
 const TAG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,40}$/;
 // Wiki-links: [[memory-name]] · names follow SLUG_PATTERN rules
 const WIKI_LINK_PATTERN = /\[\[([a-z0-9][a-z0-9_-]{0,80})\]\]/g;
-function memoryFilePath(name) {
+export function memoryFilePath(name) {
     return join(MEMORY_DIR, `${name}.md`);
 }
-function readMemory(name) {
+export function readMemory(name) {
     const fp = memoryFilePath(name);
     if (!existsSync(fp))
         return null;
@@ -196,7 +198,7 @@ function readMemory(name) {
         filePath: fp,
     };
 }
-function listMemoryFiles() {
+export function listMemoryFiles() {
     if (!existsSync(MEMORY_DIR))
         return [];
     return readdirSync(MEMORY_DIR)
@@ -575,7 +577,7 @@ function toolRelevantMemories(args) {
     }
     return sections.join("\n");
 }
-function toolDeleteMemory(args) {
+export function toolDeleteMemory(args) {
     const name = String(args.name ?? "").trim();
     if (!SLUG_PATTERN.test(name))
         throw new Error(`Invalid name "${name}".`);
@@ -913,6 +915,218 @@ function toolFindRelated(args) {
     return lines.join("\n");
 }
 // -------------------------------------------------------------
+// Git sync · multi-machine memory via git remote
+// -------------------------------------------------------------
+//
+// The killer feature for file-based memory: every dev machine has git,
+// and markdown files merge cleanly. Convert .agent-memory/ into a git
+// repo, point it at a (private) GitHub repo, and `sync push` / `sync
+// pull` becomes the multi-machine story.
+//
+// Usage flow:
+//   agent-memory sync init git@github.com:you/agent-memory.git
+//   ... save some memories ...
+//   agent-memory sync push                # commit + push
+//   # later, on another machine:
+//   agent-memory sync pull                # pull updates
+//   agent-memory sync status              # ahead/behind/clean
+//
+// Files we EXCLUDE from sync (per-machine state):
+//   .lock          · proper-lockfile per-process lock
+//   .events.jsonl  · per-machine audit log
+//   .trash/        · per-machine soft-delete staging
+const SYNC_GITIGNORE = "# Per-machine state · do not sync across devices\n" +
+    ".lock\n" +
+    ".events.jsonl\n" +
+    ".trash/\n";
+function git(args) {
+    // Inject a default commit identity so machines without `git config
+    // --global user.email` can still sync. Env vars are git's highest-
+    // precedence identity source, so they override any later config —
+    // fine for automated memory-sync where per-commit attribution
+    // doesn't matter. Honors operator overrides if set in the environment.
+    const result = spawnSync("git", args, {
+        cwd: MEMORY_DIR,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? "agent-memory",
+            GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL ?? "agent-memory@local",
+            GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? "agent-memory",
+            GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL ?? "agent-memory@local",
+        },
+    });
+    return {
+        stdout: (result.stdout ?? "").trim(),
+        stderr: (result.stderr ?? "").trim(),
+        exitCode: result.status ?? -1,
+    };
+}
+function isGitRepo() {
+    return existsSync(join(MEMORY_DIR, ".git"));
+}
+function requireRepo() {
+    if (!isGitRepo()) {
+        throw new Error(`${MEMORY_DIR} is not a git repo. Run 'agent-memory sync init <remote-url>' first.`);
+    }
+}
+function toolSyncInit(args) {
+    const remoteUrl = String(args.remote ?? args.url ?? "").trim();
+    if (!remoteUrl) {
+        throw new Error("Usage: agent-memory sync init <remote-url>\nExample: agent-memory sync init git@github.com:you/agent-memory.git");
+    }
+    ensureStorage();
+    if (isGitRepo()) {
+        return `${MEMORY_DIR} is already a git repo. Use 'sync push' or 'sync pull'.`;
+    }
+    const init = git(["init", "-b", "main"]);
+    if (init.exitCode !== 0)
+        throw new Error(`git init failed: ${init.stderr}`);
+    writeFileSync(join(MEMORY_DIR, ".gitignore"), SYNC_GITIGNORE, "utf8");
+    const addRemote = git(["remote", "add", "origin", remoteUrl]);
+    if (addRemote.exitCode !== 0)
+        throw new Error(`git remote add failed: ${addRemote.stderr}`);
+    const add = git(["add", "-A"]);
+    if (add.exitCode !== 0)
+        throw new Error(`git add failed: ${add.stderr}`);
+    const commit = git(["commit", "-m", "agent-memory · initial sync"]);
+    // commit can fail if there's nothing to commit (empty store) — that's OK
+    if (commit.exitCode !== 0 && !commit.stderr.includes("nothing to commit")) {
+        log("warn", "initial commit had no changes", { stderr: commit.stderr });
+    }
+    const push = git(["push", "-u", "origin", "main"]);
+    logEvent("sync_init", { remote: remoteUrl, pushed: push.exitCode === 0 });
+    const lines = [
+        c(ANSI.green, "✓ initialized memory sync"),
+        `  storage : ${MEMORY_DIR}`,
+        `  remote  : ${remoteUrl}`,
+        `  branch  : main`,
+    ];
+    if (push.exitCode !== 0) {
+        lines.push("");
+        lines.push(c(ANSI.yellow, "Initial push failed (remote may not exist yet):"));
+        lines.push(`  ${push.stderr.split("\n")[0]}`);
+        lines.push("");
+        lines.push("Create the empty remote on GitHub (or your git host), then run:");
+        lines.push("  agent-memory sync push");
+    }
+    else {
+        lines.push("");
+        lines.push("Future commands: 'sync push' / 'sync pull' / 'sync status' / 'sync log'");
+    }
+    return lines.join("\n");
+}
+function toolSyncStatus(_args) {
+    if (!isGitRepo()) {
+        return `${MEMORY_DIR} is not a git repo. Use 'sync init <remote-url>' to set it up.`;
+    }
+    const remote = git(["remote", "get-url", "origin"]);
+    const branch = git(["branch", "--show-current"]);
+    const fetch = git(["fetch", "origin", "--quiet"]);
+    const offline = fetch.exitCode !== 0;
+    const status = git(["status", "--porcelain"]);
+    const localChanges = status.stdout.split("\n").filter(Boolean).length;
+    const lines = [];
+    lines.push(c(ANSI.bold, "agent-memory sync · status"));
+    lines.push(`  storage : ${MEMORY_DIR}`);
+    lines.push(`  remote  : ${remote.stdout || c(ANSI.yellow, "(none configured)")}`);
+    lines.push(`  branch  : ${branch.stdout || "(unknown)"}`);
+    if (offline) {
+        lines.push(`  fetch   : ${c(ANSI.yellow, "offline — couldn't reach remote")}`);
+    }
+    lines.push("");
+    lines.push(c(ANSI.bold, "local state:"));
+    if (localChanges === 0) {
+        lines.push(`  ${c(ANSI.green, "✓ clean")} — no uncommitted changes`);
+    }
+    else {
+        lines.push(`  ${c(ANSI.yellow, `${localChanges} file(s) uncommitted`)} — run 'sync push' to commit + send`);
+    }
+    if (!offline && branch.stdout) {
+        const ahead = git(["rev-list", "--count", `origin/${branch.stdout}..HEAD`]);
+        const behind = git(["rev-list", "--count", `HEAD..origin/${branch.stdout}`]);
+        const aheadN = Number(ahead.stdout || "0");
+        const behindN = Number(behind.stdout || "0");
+        lines.push("");
+        lines.push(c(ANSI.bold, "vs origin:"));
+        if (aheadN === 0 && behindN === 0) {
+            lines.push(`  ${c(ANSI.green, "✓ in sync")}`);
+        }
+        else {
+            if (aheadN > 0)
+                lines.push(`  ${c(ANSI.cyan, `↑ ${aheadN} commit(s) ahead`)} — run 'sync push'`);
+            if (behindN > 0)
+                lines.push(`  ${c(ANSI.cyan, `↓ ${behindN} commit(s) behind`)} — run 'sync pull'`);
+        }
+    }
+    return lines.join("\n");
+}
+function toolSyncPush(args) {
+    requireRepo();
+    const message = args.message
+        ? String(args.message)
+        : `agent-memory · sync ${new Date().toISOString().slice(0, 19).replace("T", " ")}Z`;
+    const add = git(["add", "-A"]);
+    if (add.exitCode !== 0)
+        throw new Error(`git add failed: ${add.stderr}`);
+    const status = git(["status", "--porcelain"]);
+    const hadChanges = status.stdout.length > 0;
+    if (hadChanges) {
+        const commit = git(["commit", "-m", message]);
+        if (commit.exitCode !== 0)
+            throw new Error(`commit failed: ${commit.stderr}`);
+    }
+    const push = git(["push"]);
+    if (push.exitCode !== 0)
+        throw new Error(`push failed: ${push.stderr}`);
+    logEvent("sync_push", { hadChanges, commitMessage: hadChanges ? message : null });
+    return hadChanges
+        ? c(ANSI.green, `✓ committed local changes + pushed to remote\n  message: ${message}`)
+        : c(ANSI.green, `✓ nothing new locally; pushed any unpushed commits`);
+}
+function toolSyncPull(_args) {
+    requireRepo();
+    const status = git(["status", "--porcelain"]);
+    if (status.stdout) {
+        return (c(ANSI.yellow, "Local changes uncommitted.") +
+            "\nRun 'agent-memory sync push' first to commit them, then pull.");
+    }
+    const pull = git(["pull", "--ff-only"]);
+    if (pull.exitCode !== 0) {
+        return (c(ANSI.red, "✗ pull failed:") +
+            `\n  ${pull.stderr.split("\n").slice(0, 3).join("\n  ")}\n\n` +
+            `Likely diverged history (commits on both sides). Resolve manually:\n` +
+            `  cd ${MEMORY_DIR}\n` +
+            `  git pull   # do the merge by hand`);
+    }
+    logEvent("sync_pull", { output: pull.stdout.split("\n")[0] });
+    return c(ANSI.green, "✓ pulled from remote") + (pull.stdout ? `\n${pull.stdout}` : "");
+}
+function toolSyncLog(args) {
+    if (!isGitRepo())
+        return `${MEMORY_DIR} is not a git repo.`;
+    const limit = args.limit ? Number(args.limit) : 20;
+    const log = git(["log", `--max-count=${limit}`, "--pretty=format:%h %ci %s", "--no-decorate"]);
+    if (log.exitCode !== 0)
+        return `git log failed: ${log.stderr}`;
+    if (!log.stdout)
+        return "No sync history yet.";
+    const lines = [];
+    lines.push(c(ANSI.bold, `Recent sync history (last ${limit}):`));
+    lines.push("");
+    for (const line of log.stdout.split("\n")) {
+        // Format: <short-sha> <iso-date> <subject>
+        const m = line.match(/^(\S+)\s+(\S+\s+\S+\s+\S+)\s+(.*)$/);
+        if (m) {
+            lines.push(`  ${c(ANSI.cyan, m[1])}  ${c(ANSI.dim, m[2])}  ${m[3]}`);
+        }
+        else {
+            lines.push(`  ${line}`);
+        }
+    }
+    return lines.join("\n");
+}
+// -------------------------------------------------------------
 // Stats · operator dashboard
 // -------------------------------------------------------------
 function toolStats(_args) {
@@ -1022,7 +1236,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.8.1" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.10.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1434,6 +1648,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["name"],
             },
         },
+        {
+            name: "sync_status",
+            description: "Report the git-sync state of the memory store: remote URL, branch, local uncommitted files, commits ahead/behind origin. Use this before opening a new session to know if you have stale memories from another machine.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "sync_push",
+            description: "Commit any local memory changes and push to the configured git remote. Auto-generates a timestamped commit message if none provided. Use at the end of a session to make memories available on your other machines.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: {
+                        type: "string",
+                        description: "Optional commit message. Defaults to a timestamp.",
+                    },
+                },
+            },
+        },
+        {
+            name: "sync_pull",
+            description: "Pull memory updates from the configured git remote (fast-forward only). Run at the start of a session to get memories saved on other machines. Refuses to pull if there are uncommitted local changes.",
+            inputSchema: { type: "object", properties: {} },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1480,6 +1717,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "find_related":
                 result = toolFindRelated(args);
                 break;
+            case "sync_status":
+                result = toolSyncStatus(args);
+                break;
+            case "sync_push":
+                result = toolSyncPush(args);
+                break;
+            case "sync_pull":
+                result = toolSyncPull(args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -1515,6 +1761,8 @@ const CLI_COMMANDS = new Set([
     "verify",
     "backlinks",
     "related",
+    "sync",
+    "ui",
     "import-claude-code",
     "help",
     "--help",
@@ -1670,6 +1918,36 @@ async function cliMain(command, rest) {
                 }) + "\n");
                 return 0;
             }
+            case "sync": {
+                const sub = positional[0];
+                if (!sub) {
+                    throw new Error("Usage: agent-memory sync <init|push|pull|status|log>\n" +
+                        "  init <remote-url>       set up a new memory-sync repo\n" +
+                        "  push [--message X]      commit + push local changes\n" +
+                        "  pull                    fast-forward pull from remote\n" +
+                        "  status                  show local + remote state\n" +
+                        "  log [--limit N]         recent sync commit history");
+                }
+                switch (sub) {
+                    case "init":
+                        process.stdout.write(toolSyncInit({ remote: positional[1] }) + "\n");
+                        return 0;
+                    case "push":
+                        process.stdout.write(toolSyncPush({ message: flags.message }) + "\n");
+                        return 0;
+                    case "pull":
+                        process.stdout.write(toolSyncPull({}) + "\n");
+                        return 0;
+                    case "status":
+                        process.stdout.write(toolSyncStatus({}) + "\n");
+                        return 0;
+                    case "log":
+                        process.stdout.write(toolSyncLog({ limit: flags.limit ? Number(flags.limit) : undefined }) + "\n");
+                        return 0;
+                    default:
+                        throw new Error(`Unknown sync subcommand: ${sub}. Try 'sync' for help.`);
+                }
+            }
             case "log": {
                 process.stdout.write(toolLogEvents({
                     tail: flags.tail ? Number(flags.tail) : undefined,
@@ -1677,6 +1955,13 @@ async function cliMain(command, rest) {
                 }) + "\n");
                 return 0;
             }
+            case "ui": {
+                // Dynamic import so Ink + React only load when the TUI runs,
+                // keeping cold-start fast for MCP server + every other CLI command.
+                const { runTui } = await import("./tui.js");
+                await runTui();
+                return 0;
+            }
             case "import-claude-code": {
                 return importClaudeCode({
                     source: flags.source ? String(flags.source) : undefined,
@@ -1728,6 +2013,14 @@ COMMANDS
   backlinks <name>                         List memories that link to <name> via [[wiki-links]].
   related <name> [--max N]                 Surface related memories via outbound + inbound links,
                                            shared tags, type match, content similarity.
+  sync <init|push|pull|status|log>         Multi-machine memory via git remote.
+    sync init <remote-url>                   Initialize .agent-memory/ as a git repo + push.
+    sync push [--message X]                  Commit local changes + push to remote.
+    sync pull                                Fast-forward pull from remote.
+    sync status                              Show local + ahead/behind state.
+    sync log [--limit N]                     Recent sync commit history.
+  ui                                       Launch the TUI · browse, filter, search, edit memories
+                                           in a clean terminal interface (Ink-based).
   import-claude-code [--source <path>] [--project <pat>] [--overwrite] [--dry-run]
                                            Walk ~/.claude/projects/*/memory/ and
                                            import each memory into the current store.
@@ -1850,7 +2143,12 @@ async function main() {
     await server.connect(transport);
     process.stderr.write(`agent-memory-mcp · storage: ${MEMORY_DIR}\n`);
 }
-main().catch((err) => {
-    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
-    process.exit(1);
-});
+// Only auto-run main() when invoked directly. Importing this file
+// (e.g. from src/tui.tsx) should not trigger the dispatch.
+const isEntryPoint = process.argv[1] && process.argv[1] === fileURLToPath(import.meta.url);
+if (isEntryPoint) {
+    main().catch((err) => {
+        process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/tui.js

@@ -0,0 +1,183 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * agent-memory-mcp · TUI
+ *
+ * The visual face of the project — Ink-based terminal UI for browsing,
+ * filtering, searching, and editing memories.
+ *
+ * Layout:
+ *   ┌─ agent-memory ──────────────────────────────────────────┐
+ *   │ [all] user feedback project reference  ·  N memories     │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │ memory list (scrolling)                                  │
+ *   │   ▶ highlighted name  [type]  · tags                     │
+ *   │     description                                          │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │ detail pane for highlighted memory                       │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │ key hints footer                                         │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Launched via `agent-memory ui`. Dynamic-imported from index.ts so
+ * Ink + React only load when the TUI is actually invoked.
+ */
+import { Box, render, Text, useApp, useInput, useStdout } from "ink";
+import TextInput from "ink-text-input";
+import { spawnSync } from "node:child_process";
+import { useEffect, useMemo, useState } from "react";
+import Fuse from "fuse.js";
+import { listMemoryFiles, MEMORY_DIR, memoryFilePath, readMemory, toolDeleteMemory, } from "./index.js";
+const TYPE_FILTERS = ["all", "user", "feedback", "project", "reference"];
+function loadAllMemories() {
+    return listMemoryFiles()
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function filterMemories(memories, typeFilter, query) {
+    let list = memories;
+    if (typeFilter !== "all")
+        list = list.filter((m) => m.type === typeFilter);
+    if (query.trim()) {
+        const fuse = new Fuse(list, {
+            includeScore: true,
+            threshold: 0.4,
+            ignoreLocation: true,
+            keys: [
+                { name: "name", weight: 3 },
+                { name: "description", weight: 2 },
+                { name: "body", weight: 1 },
+            ],
+        });
+        return fuse.search(query).map((r) => r.item);
+    }
+    return list;
+}
+const typeColor = {
+    user: "cyan",
+    feedback: "yellow",
+    project: "green",
+    reference: "magenta",
+};
+const App = () => {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const [state, setState] = useState({
+        memories: loadAllMemories(),
+        selected: 0,
+        typeFilter: "all",
+        searchMode: false,
+        searchQuery: "",
+        confirmDelete: null,
+        status: null,
+    });
+    const visible = useMemo(() => filterMemories(state.memories, state.typeFilter, state.searchQuery), [state.memories, state.typeFilter, state.searchQuery]);
+    // Keep the selection in range when filters shrink the list
+    useEffect(() => {
+        if (state.selected >= visible.length && visible.length > 0) {
+            setState((s) => ({ ...s, selected: Math.max(0, visible.length - 1) }));
+        }
+        else if (visible.length === 0 && state.selected !== 0) {
+            setState((s) => ({ ...s, selected: 0 }));
+        }
+    }, [visible.length, state.selected]);
+    const current = visible[state.selected];
+    const refresh = () => setState((s) => ({ ...s, memories: loadAllMemories(), status: "refreshed" }));
+    useInput((input, key) => {
+        if (state.searchMode)
+            return; // TextInput component handles search input
+        // Delete confirmation flow
+        if (state.confirmDelete) {
+            if (input === "y" || input === "Y") {
+                try {
+                    toolDeleteMemory({ name: state.confirmDelete });
+                    setState((s) => ({
+                        ...s,
+                        memories: loadAllMemories(),
+                        confirmDelete: null,
+                        status: `deleted "${state.confirmDelete}" (in .trash/)`,
+                    }));
+                }
+                catch (err) {
+                    setState((s) => ({
+                        ...s,
+                        confirmDelete: null,
+                        status: `delete failed: ${err.message}`,
+                    }));
+                }
+            }
+            else if (input === "n" || input === "N" || key.escape) {
+                setState((s) => ({ ...s, confirmDelete: null, status: "delete cancelled" }));
+            }
+            return;
+        }
+        if (input === "q" || (key.ctrl && input === "c")) {
+            exit();
+            return;
+        }
+        if (key.upArrow || input === "k") {
+            setState((s) => ({ ...s, selected: Math.max(0, s.selected - 1), status: null }));
+            return;
+        }
+        if (key.downArrow || input === "j") {
+            setState((s) => ({
+                ...s,
+                selected: Math.min(Math.max(0, visible.length - 1), s.selected + 1),
+                status: null,
+            }));
+            return;
+        }
+        // Type filter quick-keys
+        const typeKeyMap = {
+            "0": "all",
+            "1": "user",
+            "2": "feedback",
+            "3": "project",
+            "4": "reference",
+        };
+        if (typeKeyMap[input]) {
+            setState((s) => ({ ...s, typeFilter: typeKeyMap[input], selected: 0, status: null }));
+            return;
+        }
+        if (input === "/") {
+            setState((s) => ({ ...s, searchMode: true, status: null }));
+            return;
+        }
+        if (input === "r") {
+            refresh();
+            return;
+        }
+        if (input === "e" && current) {
+            const editor = process.env.EDITOR || (process.platform === "win32" ? "notepad" : "vi");
+            const fp = memoryFilePath(current.name);
+            // Suspend Ink rendering, spawn editor, then refresh after exit
+            stdout?.write("\x1bc"); // reset terminal to give the editor a clean canvas
+            const result = spawnSync(editor, [fp], { stdio: "inherit" });
+            setState((s) => ({
+                ...s,
+                memories: loadAllMemories(),
+                status: result.status === 0
+                    ? `edited "${current.name}" in ${editor}`
+                    : `editor exited with code ${result.status}`,
+            }));
+            return;
+        }
+        if (input === "d" && current) {
+            setState((s) => ({ ...s, confirmDelete: current.name, status: null }));
+            return;
+        }
+    });
+    const onSearchSubmit = () => setState((s) => ({ ...s, searchMode: false, selected: 0 }));
+    const onSearchChange = (value) => setState((s) => ({ ...s, searchQuery: value }));
+    return (_jsxs(Box, { flexDirection: "column", width: "100%", children: [_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, children: "agent-memory" }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), TYPE_FILTERS.map((t, i) => (_jsxs(Text, { bold: state.typeFilter === t, color: state.typeFilter === t ? "green" : "gray", children: [i > 0 ? "  " : "", "[", i, "] ", t] }, t))), _jsxs(Text, { dimColor: true, children: [" · ", visible.length, " of ", state.memories.length, state.searchQuery && ` matching "${state.searchQuery}"`] })] }), state.searchMode && (_jsxs(Box, { paddingX: 1, children: [_jsx(Text, { color: "cyan", children: "/ " }), _jsx(TextInput, { value: state.searchQuery, onChange: onSearchChange, onSubmit: onSearchSubmit, placeholder: "fuzzy search \u00B7 enter to confirm" })] })), _jsxs(Box, { flexDirection: "column", paddingX: 1, children: [visible.length === 0 ? (_jsx(Text, { dimColor: true, children: "(no memories match)" })) : (visible.slice(0, 12).map((m, i) => {
+                        const isSelected = i === state.selected;
+                        return (_jsxs(Box, { children: [_jsxs(Text, { color: isSelected ? "green" : undefined, bold: isSelected, children: [isSelected ? "▶ " : "  ", m.name] }), _jsxs(Text, { color: typeColor[m.type] ?? "gray", children: [" [", m.type, "]"] }), m.tags.length > 0 ? (_jsxs(Text, { dimColor: true, children: [" · ", m.tags.join(" · ")] })) : null] }, m.name));
+                    })), visible.length > 12 && (_jsxs(Text, { dimColor: true, children: [" ... +", visible.length - 12, " more (filter down with /)"] }))] }), current && (_jsxs(Box, { borderStyle: "single", borderColor: "gray", flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, children: current.name }), _jsx(Text, { dimColor: true, children: current.description }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [current.body
+                                .split("\n")
+                                .slice(0, 10)
+                                .map((line, i) => (_jsx(Text, { dimColor: line.startsWith("#") ? false : true, children: line || " " }, i))), current.body.split("\n").length > 10 && (_jsx(Text, { dimColor: true, children: "... (truncated \u00B7 press 'e' to open in editor)" }))] })] })), _jsxs(Box, { paddingX: 1, flexDirection: "column", children: [state.confirmDelete ? (_jsxs(Text, { color: "yellow", children: ["Delete \"", state.confirmDelete, "\"? (y/n) \u00B7 soft-delete, recoverable from .trash/"] })) : (_jsx(Text, { dimColor: true, children: "\u2191\u2193/jk navigate \u00B7 0-4 type filter \u00B7 / search \u00B7 e edit \u00B7 d delete \u00B7 r refresh \u00B7 q quit" })), state.status && _jsxs(Text, { color: "cyan", children: ["\u00B7 ", state.status] }), _jsxs(Text, { dimColor: true, children: ["storage: ", MEMORY_DIR] })] })] }));
+};
+export async function runTui() {
+    const { waitUntilExit } = render(_jsx(App, {}));
+    await waitUntilExit();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Markdown memory for AI agents. Plain files you can read, edit, grep, and commit. The only MCP memory server that isn't a database.",
   "type": "module",
@@ -56,11 +56,15 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "fuse.js": "^7.3.0",
     "gray-matter": "^4.0.3",
-    "proper-lockfile": "^4.1.2"
+    "ink": "^7.0.3",
+    "ink-text-input": "^6.0.0",
+    "proper-lockfile": "^4.1.2",
+    "react": "^19.2.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.2.15",
     "prettier": "^3.8.3",
     "typescript": "^5.7.2",
     "vitest": "^4.1.7"