@agentage/mcp-memory
OfficialThis server exposes a local Markdown memory vault as six MCP tools over stdio for durable notes and knowledge.
Search memories by literal case-insensitive substring across titles/bodies/tags, ranked by match count, with tag/folder filters and pagination.
Read a single memory by exact path, returning full frontmatter, body, tags, and timestamps.
List/browse the memory folder tree with file counts, tag filtering, depth control, and truncation signals.
Write a new memory or fully overwrite an existing one at a path, including frontmatter.
Edit an existing memory in place using exact string replacement, append, full-body replace, or frontmatter shallow merge.
Delete a memory via soft-delete, recoverable from git history.
Store durable knowledge and notes only; secrets, passwords, API keys, one-time codes, and payment/government identifiers are refused.
Optionally emit telemetry if
@agentage/observabilityis installed and configured; otherwise telemetry is off by default.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@agentage/mcp-memory list my recent memories"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@agentage/server-memory
The MCP server for agentage Memory exposes your local vaults
(~/.agentage/vaults.json, read through @agentage/memory-core)
as the frozen 6 memory__* tools over stdio. The open, cross-vendor counterpart to
@modelcontextprotocol/server-memory.
This package is intentionally small - it is just the MCP definition (the 6-tool Zod
schema + .mcpc.json, the text renderer, createMemoryServer, and a ~15-line stdio bin).
All memory logic (backends, git, search, routing) lives in @agentage/memory-core.
Use it
# one-time, offline: scaffold ~/.agentage + a starter vault (memory-core's `init`)
npx @agentage/server-memory # serves ~/.agentage/vaults.json over stdioPoint any stdio MCP client (VS Code, Windsurf, Zed, Claude Desktop) at npx @agentage/server-memory.
Related MCP server: folio
Telemetry (optional, off by default)
Nothing is collected and nothing extra is installed: @agentage/observability is not a
dependency, because npx @agentage/server-memory should stay a small cold start. Install the kit
alongside and the bin picks it up on its own - traces and one wide event per tool call:
npm i -g @agentage/observabilityAbsent, the server behaves exactly as before (AGENTAGE_DEBUG=1 prints one stderr line saying the
kit was not found). Present, it is still inert until OTEL_EXPORTER_OTLP_ENDPOINT names a
collector; OTEL_SERVICE_NAME defaults to agentage-server-memory. Either way stdout carries
only JSON-RPC - every kit line goes to stderr, which test/observability.test.ts asserts in both
directions.
Develop
npm install # links @agentage/memory-core via file:../memory-core
npm test # vitest: contract (tools/list = 6) + tools (in-memory) + e2e (init -> spawned bin -> round-trip)
npm run verify # type-check + lint + format:check + test + build@agentage/memory-core is a local file: link until both packages publish to npm; build
core before running here (the e2e does this automatically). The 6-tool schema and
.mcpc.json snapshot are the frozen MCP contract - keep them in sync if the contract changes.
Available Tools
6 toolsmemory__deleteDelete memoryADestructive
Soft-delete (forget) a memory by path; recoverable from git history. Returns not-found if the path does not exist. To remove only part of a memory, use memory__edit.
Inputs: path (required). Returns: path, deleted
memory__editEdit memoryA
Amend an EXISTING memory in place: mode=str_replace swaps one exact text match (old_str -> new_str) without resending the note - the default choice for small changes; append adds to the end; replace overwrites the whole body; frontmatter shallow-merges. Fails with not-found if the path does not exist - use memory__write to create. Do not introduce secrets, passwords, API keys, one-time codes, or payment/government identifiers (these are refused).
Inputs: path (required), body, mode, new_str, +2 more. Returns: path, updated
memory__listBrowse memoryARead-only
Browse the memory as a folder tree: the files and subfolders under a folder, 2 levels deep by default, with per-folder file counts - no bodies, no ranking. Use to see what exists and how it is organized, or to list every note carrying a tag (tags filter); have a keyword to rank by instead? use memory__search. A folder shown without its own entries has more inside: call memory__list again with that folder. Folders over the per-folder entry limit are flagged truncated and not expanded - browse them directly or narrow with memory__search.
Inputs: tags, depth, folder. Returns: files, folder, entries, truncated
memory__readRead memoryARead-only
Read ONE memory by its exact path: returns full frontmatter + body. Use a path you got from memory__search/list, a prior write/edit, or the user - do not invent or guess one from a title. No known path? use memory__search first.
Inputs: path (required). Returns: body, path, tags, title, +3 more
memory__searchSearch memoryARead-only
Find memories by literal text, ranked by match count. Matches the query as ONE case-insensitive substring (not semantic, not tokenized) across titles/bodies/tags - so search a SINGLE keyword, not a phrase. Returns path+snippet+score (score = number of matches, not a relevance %), never full bodies. Use when you have a keyword to rank by; to browse the folder tree instead, use memory__list. Zero hits? try a synonym.
Inputs: query (required), tags, limit, cursor, +1 more. Returns: results, nextCursor
memory__writeWrite memoryAIdempotent
Create a NEW memory or fully OVERWRITE an existing one at path - replaces the entire body and frontmatter (idempotent; the saved memory persists for every AI). Use when you have the complete final content. To change only part of an existing memory, use memory__edit. Store durable knowledge and notes only - never secrets, passwords, API keys, one-time codes, or payment/government identifiers (these are refused).
Inputs: body (required), path (required), frontmatter. Returns: path, updated
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a unique, well-defined purpose: create/overwrite (write), modify existing (edit), delete (delete), read by path (read), browse folder tree (list), and keyword search (search). No overlapping functionality.
All tools follow the 'memory__<verb>' pattern with clear, single-word verbs (delete, edit, list, read, search, write). Consistent and predictable.
Six tools cover the essential CRUD and browsing operations for a hierarchical memory store. The count is well-scoped without unnecessary complexity.
Core CRUD and browsing are covered. Minor gaps like renaming or moving memories exist, but agents can work around by editing content or using multiple steps.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Shared long-term memory vault for AI agents with 20 MCP tools.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Related MCP Servers
- AlicenseAqualityDmaintenanceExposes a verified tool registry (calculator, sandboxed file read, web fetch) over MCP stdio, enabling any MCP-capable client to reuse the same tools from the inspectable ReAct loop.3MIT
- AlicenseNot gradedqualityBmaintenanceServes a unified local memory bank over a stdio MCP server, exposing five tools and one resource so any MCP-capable harness can list, search, and read memories imported from Claude Code, Codex, Cursor, Kimi Code, and ZCode. It gives agents a single read-only view of user preferences, feedback, project state, and reference material stored as plain Markdown files.MIT
- AlicenseNot gradedqualityCmaintenanceExposes a layered long-term memory store — persistent self blocks, four-tier scoped retrieval, knowledge graph, and signed knowledge capsules — over stdio so any MCP-capable client can use the same 15 memory tools and shared ACL. It lets Claude Desktop, IDE agents, and custom orchestrators mount that store without depending on the DeepSeek Harness runtime.MIT
- AlicenseAqualityCmaintenanceExposes 16 local stdio MCP tools that give Codex-style clients project-isolated persistent memory, local ONNX-based semantic search, and durable task tracking that survives across sessions and concurrent clients, without executing agents, hosting a model, or contacting model providers.16MIT