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

package/README.md

@@ -64,17 +64,15 @@ If you want vector similarity search, semantic recall, or auto-relation extracti
 
 ## Install
 
-### Quick start (works today, no npm needed)
+### From npm (recommended)
 
 ```bash
-npx -y github:xultrax-web/agent-memory-mcp
+npx -y @xultrax-web/agent-memory-mcp
 ```
 
-### From npm (once published — landing v0.4.0)
+### Listed in the MCP Registry
 
-```bash
-npx -y @xultrax-web/agent-memory-mcp
-```
+`io.github.xultrax-web/agent-memory-mcp` · browse at https://registry.modelcontextprotocol.io
 
 ### Build locally
 
@@ -103,7 +101,7 @@ Same JSON, slightly different paths per client.
   "mcpServers": {
     "agent-memory": {
       "command": "npx",
-      "args": ["-y", "github:xultrax-web/agent-memory-mcp"]
+      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
     }
   }
 }
@@ -117,7 +115,7 @@ Cline → MCP Servers → Add:
 {
   "agent-memory": {
     "command": "npx",
-    "args": ["-y", "github:xultrax-web/agent-memory-mcp"]
+    "args": ["-y", "@xultrax-web/agent-memory-mcp"]
   }
 }
 ```
@@ -131,7 +129,7 @@ Cline → MCP Servers → Add:
   "mcpServers": {
     "agent-memory": {
       "command": "npx",
-      "args": ["-y", "github:xultrax-web/agent-memory-mcp"]
+      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
     }
   }
 }
@@ -140,7 +138,7 @@ Cline → MCP Servers → Add:
 > **Windows note:** if `npx` doesn't resolve cleanly, wrap with `cmd /c`:
 >
 > ```json
-> { "command": "cmd", "args": ["/c", "npx", "-y", "github:xultrax-web/agent-memory-mcp"] }
+> { "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] }
 > ```
 
 ### Continue.dev
@@ -155,7 +153,7 @@ Cline → MCP Servers → Add:
         "transport": {
           "type": "stdio",
           "command": "npx",
-          "args": ["-y", "github:xultrax-web/agent-memory-mcp"]
+          "args": ["-y", "@xultrax-web/agent-memory-mcp"]
         }
       }
     ]
@@ -272,6 +270,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)
@@ -429,25 +428,54 @@ 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+:**
+**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
+
+**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)
 
 ---
 
 ## Roadmap
 
-- **v0.2** — MCP Resources support, Claude Code import script (`agent-memory import-claude-code`), CLI mode
-- **v0.3** — Atomic writes, soft delete, schema versioning, doctor command
-- **v0.4** — Structured event log, stats command, color output
-- **v0.5** — Fuzzy search (Fuse.js), BM25 ranking, snippet highlighting
-- **v0.7** — Comprehensive test suite, multi-client compatibility matrix
-- **v0.9** — npm publish + MCP Registry submission
-- **v1.0** — Public launch
-
-Beyond v1.0: sync backends (git remote, S3), web UI, team mode, browser extension, optional embeddings sidecar.
+### Released
+
+| Version   | Highlights                                                                                          |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| v0.1      | Five-tool MVP, file storage, four-client config snippets                                            |
+| v0.2      | MCP Resources, Claude Code import (`agent-memory import-claude-code`), CLI mode, prettier baseline  |
+| v0.3      | Atomic writes, file locking, soft delete + `restore_memory`, `doctor` repair, schema versioning     |
+| v0.4      | Append-only event log (`.events.jsonl`), `stats` dashboard, `log_events` browser, color output      |
+| v0.5      | Fuzzy search via Fuse.js, relevance scoring, body-context snippets, `relevant_memories`, pagination |
+| v0.6      | 25+ Vitest tests, GitHub Actions CI (Node 20/22/24 matrix), `COMPATIBILITY.md`                      |
+| v0.7      | MCP Prompts (4 starter workflows), `verify_memory`, conflict detection on save                      |
+| v0.8      | Tags, `[[wiki-links]]`, `find_backlinks`, `find_related`                                            |
+| v0.8.1    | Trusted Publishing live · tokenless OIDC publishes to npm + MCP Registry on git tag                 |
+| **v0.9**  | **`agent-memory sync` · multi-machine memory via git remote (init/push/pull/status/log)**           |
+| **v0.10** | **Ink-based TUI · `agent-memory ui` for visual browsing, search, and editing**                      |
+
+### Coming next
+
+- Folder support inside the store (`.agent-memory/work/`, `.agent-memory/personal/`) for multi-context separation
+- Auto-context loading — server hook that auto-fires `relevant_memories` before each LLM turn so context flows transparently
+- Memory packs — export/import shareable `.tar.gz` bundles of curated memories
+- Browser companion UI (`agent-memory web`) for non-terminal users
+- TUI polish — file-watching for auto-refresh, inline editing, sync push/pull as keybindings
+
+### Beyond
+
+Optional local-embeddings sidecar (transformers.js, no API), team mode with diff/merge, browser extension to capture from chatgpt.com / claude.ai → memory, mobile companion.
 
 Open an issue if you want one of these before I get to it.
 

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.1" }, { 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.1",
   "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"