Click on "Install 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.
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.
# one-time, offline: scaffold ~/.agentage + a starter vault
# (memory-core's `init`, also surfaced by the agentage CLI)
npx @agentage/server-memory # serves ~/.agentage/vaults.json over stdioPoint any stdio MCP client (Windsurf, Zed, Claude Desktop) at npx @agentage/server-memory.
Related MCP server: memory-mcp
The server builder is transport-agnostic, so the agentage CLI reuses the exact same pieces and only swaps the transport:
import { createMemoryServer, loadLocalServer } from '@agentage/server-memory';
// stdio bin: await (await loadLocalServer()).connect(new StdioServerTransport());
// CLI daemon: const server = createMemoryServer(registry, { scope: 'local' });
// await server.connect(new StreamableHTTPServerTransport(...));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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Exact POSIX .md address - not a title or search query. Case-sensitive, no leading slash. e.g. work/tasks/foo.md |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| deleted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true), description adds that delete is soft, recoverable from git history, and returns not-found for nonexistent paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no redundant information. Each sentence adds value: (1) what it does, (2) error behavior, (3) when to use alternative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 simple parameter and presence of output schema, description covers all needed aspects: purpose, usage, behavioral details, and parameter syntax. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers path parameter completely. Description adds crucial context: exact POSIX .md address, case-sensitive, no leading slash, example. Greatly aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action (soft-delete), resource (memory by path), and distinguishes from sibling tool memory__edit. Also explains recoverability and error behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (delete entire memory by path) and when to use alternative (use memory__edit to remove part). Provides guidance on recoverability and 'not-found' response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Markdown body, excluding frontmatter (no --- fences). With mode=replace it becomes the new body; with mode=append it is added to the end. Not used with mode=str_replace. Omit to change only frontmatter. | |
| mode | No | Optional. "str_replace" swaps old_str for new_str in place; "append" adds body to the end; omit or "replace" overwrites the whole body. Frontmatter always shallow-merges regardless. | |
| path | Yes | Exact POSIX .md address - not a title or search query. Case-sensitive, no leading slash. e.g. work/tasks/foo.md | |
| new_str | No | mode=str_replace only. The replacement text. Omit to delete old_str. | |
| old_str | No | mode=str_replace only. The exact existing body text to replace - must match verbatim (including whitespace) and appear exactly once. Read the memory first to copy it. | |
| frontmatter | No | YAML metadata as a key->value map (no --- fences), e.g. {"type":"task","status":"active","tags":["project"]}. write replaces the whole map; edit shallow-merges top-level keys (nested values replaced wholesale; a key cannot be removed via edit - use write to fully replace) |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| updated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses failure condition for non-existent path, security constraints, and mode behaviors. Annotations provide no hints, so description carries the burden well. Could mention concurrency or idempotency, but not required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph packs mode explanations, failure condition, and security note. No fluff. Could be slightly more structured (e.g., bullet list for modes), but still concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 params, 1 required, output schema present, and sparse annotations, the description covers all critical aspects: modes, error case, security, parameter usage. Omits nothing essential for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by explaining which parameters interact with which modes (e.g., body not used with str_replace) and clarifying frontmatter merge behavior. Schema coverage is 100%, so baseline is high; description enhances it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it amends an existing memory and lists distinct modes, distinguishing it from memory__write (create) and other siblings. Verb 'edit' is specific and resource-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use memory__write if path doesn't exist, and explains when to use each mode. Security warning against secrets provides additional guidance. Does not fully cover when not to use this tool vs others, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to filter by (frontmatter tags: or inline #tag), AND-matched (all must be present), case-sensitive, bare without #. e.g. [project, active]. Omit = no tag filter | |
| depth | No | Optional. 1 = direct children of the folder only; 2 (default) = also expand each subfolder one more level. | |
| folder | No | Folder, POSIX, no leading slash (trailing slash optional), e.g. work/tasks. Matches that folder only - not a string prefix. Omit = whole memory |
| Name | Required | Description |
|---|---|---|
| files | Yes | Total files under the browsed folder (after the tags filter) |
| folder | Yes | The browsed folder, normalized; empty = memory root |
| entries | Yes | |
| truncated | Yes | True = something was omitted anywhere in this response (a folder over the per-folder limit, or the response budget); narrow with a subfolder or memory__search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint false. Description adds behavioral details: no bodies/ranking, truncation flagged, how to expand folders, tag matching semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph but packed with useful information. Front-loaded with purpose. Could be broken into shorter sentences, but no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and full parameter descriptions, this covers usage, edge cases (truncation), alternatives, and drill-down behavior. Complete for a browse tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% (baseline 3). Description adds context: tags AND-matched, case-sensitive, bare; depth defaults to 2; folder exact match (not prefix). Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it browses memory as a folder tree, listing files/subfolders 2 levels deep with counts, no bodies or ranking. It distinguishes from memory__search for keyword ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use (see organization, list notes by tag), when to drill down (call again if folder shown without entries), and alternative (memory__search for ranking).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Exact POSIX .md address - not a title or search query. Case-sensitive, no leading slash. e.g. work/tasks/foo.md |
| Name | Required | Description |
|---|---|---|
| body | Yes | |
| path | Yes | |
| tags | Yes | |
| title | Yes | |
| deleted | Yes | |
| updated | Yes | |
| frontmatter | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that read returns 'full frontmatter + body' and warns about case-sensitivity and leading slash, providing useful behavioral details beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, existing output schema, and clear annotations, the description fully covers purpose, usage, parameter semantics, and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description. The description reinforces the exact path requirement, adds examples, and clarifies it's not a title or query, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('memory by its exact path'), clearly stating it returns frontmatter and body. It distinguishes from sibling tools like memory__search (for finding paths) and memory__list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use ('path from search/list/prior operation'), when not to ('do not invent or guess'), and alternative ('use memory__search first') is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to filter by (frontmatter tags: or inline #tag), AND-matched (all must be present), case-sensitive, bare without #. e.g. [project, active]. Omit = no tag filter | |
| limit | No | Optional. Max results in this page; defaults to 20, capped at 50. | |
| query | Yes | Literal text to find (case-insensitive). Matched as ONE exact substring across titles/bodies/tags - not semantic, not split into words - so a multi-word query matches only that exact phrase; search a SINGLE distinctive keyword. e.g. pkce | |
| cursor | No | Opaque pagination token - pass the previous response's nextCursor here verbatim for the next page. Omit for the first page; never construct or edit it. | |
| folder | No | Folder, POSIX, no leading slash (trailing slash optional), e.g. work/tasks. Matches that folder only - not a string prefix. Omit = whole memory |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| nextCursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses match as ONE case-insensitive substring across titles/bodies/tags, returns path+snippet+score (count of matches, not relevance), and never full bodies. Annotations already declare readOnlyHint=true; description adds valuable behavioral context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise yet packed with useful information. Front-loaded with purpose, then key constraints, then usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and output schema, the description covers all necessary aspects: when/why to use, how query works, return format, pagination, and filtering. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters are described in schema (100% coverage). Description adds meaning: explains query is literal substring, gives example 'pkce', clarifies score meaning, and notes cursor is opaque. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Find memories by literal text, ranked by match count.' Differentiates from sibling memory__list by specifying when to use that tool instead. Describes query behavior as literal substring match, not semantic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (keyword search) and when not (browsing folder tree → memory__list). Advises to try synonym on zero hits. Provides query format guidance (single keyword, not phrase).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The complete Markdown body, excluding frontmatter (no --- fences). write overwrites the entire existing body. | |
| path | Yes | Exact POSIX .md address - not a title or search query. Case-sensitive, no leading slash. e.g. work/tasks/foo.md | |
| frontmatter | No | YAML metadata as a key->value map (no --- fences), e.g. {"type":"task","status":"active","tags":["project"]}. write replaces the whole map; edit shallow-merges top-level keys (nested values replaced wholesale; a key cannot be removed via edit - use write to fully replace) |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| updated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'fully OVERWRITE' which is destructive, but the annotation destructiveHint is false. This is a contradiction. The description also adds context about idempotency and persistence, but the contradiction undermines transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a security warning, front-loaded with purpose and behavior. Every sentence is essential with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, output schema exists, and sibling context, the description covers purpose, usage, parameter details, behavior, and security. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. Description adds value by clarifying that body excludes frontmatter, path is exact POSIX .md address with case-sensitivity, and frontmatter is YAML map with overwrite behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Create' and 'overwrite' with the resource 'memory at path', and distinguishes from sibling tool memory__edit by noting it replaces entire content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when you have the complete final content' and recommends memory__edit for partial changes. Also warns against storing secrets, providing clear when-to-use and when-not-to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.0.3memory__deletememory__editmemory__listmemory__readmemory__searchmemory__writeEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared long-term memory vault for AI agents with 20 MCP tools.
Shared memory and actions for Claude, Kiro, OpenAI, Cursor, and other MCP-compatible AI clients.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/agentage/server-memory'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
