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

package/README.md

@@ -272,6 +272,7 @@ agent-memory sync init git@github.com:you/agent-memory.git    # multi-machine se
 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)
@@ -418,6 +419,16 @@ 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.
 
+**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.
@@ -429,11 +440,12 @@ This server is built to be used daily, not to demo well once.
 - 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.10+:**
+**Landing in v0.11+:**
 
-- TUI / web UI for browsing + editing memories in a clean interface
 - Folder support (`.agent-memory/work/`, `.agent-memory/personal/`)
 - 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

@@ -30,6 +30,7 @@ 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
@@ -43,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");
@@ -178,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;
@@ -197,7 +198,7 @@ function readMemory(name) {
         filePath: fp,
     };
 }
-function listMemoryFiles() {
+export function listMemoryFiles() {
     if (!existsSync(MEMORY_DIR))
         return [];
     return readdirSync(MEMORY_DIR)
@@ -576,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}".`);
@@ -1235,7 +1236,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.9.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.10.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1761,6 +1762,7 @@ const CLI_COMMANDS = new Set([
     "backlinks",
     "related",
     "sync",
+    "ui",
     "import-claude-code",
     "help",
     "--help",
@@ -1953,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,
@@ -2010,6 +2019,8 @@ COMMANDS
     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.
@@ -2132,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.9.0",
+  "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"