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., "@Memento Remember my favorite color is blue"
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.
Persistent, searchable memory for AI assistants.
Memento is an MCP server that gives Claude long-term memory across sessions, projects, and machines. Store what you learn, search it later, recall only what you need.
No databases. No embedding models. No external services. Plain files, runs locally.
Most AI assistants forget everything the moment a session ends. Memento fixes that by giving Claude a persistent store it can read and write to across sessions.
The design is built around two-phase retrieval: search returns compact snippets so the AI can decide what's relevant, then recall fetches full content only for the entries it actually needs. This keeps context windows lean and costs low.
Storage is append-only JSONL files on disk. Search is BM25, the same probabilistic ranking that powers most search engines. No ML, no APIs, just fast deterministic text matching.
Related MCP server: Local Brain MCP
claude plugin add github:Kotrotsos/memento-coreThe plugin auto-builds on first use via a SessionStart hook (takes about 10 seconds). After that it's instant.
git clone https://github.com/Kotrotsos/memento-core.git
cd memento-core
npm install && npm run buildThen register the MCP server. Add this to your ~/.mcp.json or a project-level .mcp.json:
{
"mcpServers": {
"memento": {
"command": "node",
"args": ["/path/to/memento-core/build/index.js"]
}
}
}Restart Claude Code. You should see the memory_* tools available.
Memento exposes five tools over the Model Context Protocol.
memory_storeCreate a new memory or update an existing one.
memory_store(content, namespace?, tags?, id?, relations?, ttl?)Parameter | Type | Default | Description |
| string | required | The memory text |
| string |
| Where to file it: |
| string[] |
| Labels for filtering: |
| string | auto | Provide an existing ID to update that memory |
| string[] |
| IDs of related memories |
| string | permanent | ISO 8601 expiry. After this timestamp, the memory is excluded from results |
Example
{
"content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append).",
"namespace": "decisions",
"tags": ["architecture", "storage"]
}memory_searchSearch memories with BM25 ranking. Returns snippets, not full content.
memory_search(query, namespace?, tags?, limit?)Parameter | Type | Default | Description |
| string | required | Search terms |
| string | all | Scope results to a namespace |
| string[] | — | Filter by tags (AND logic, all must match) |
| number |
| Max results to return |
Response
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"namespace": "decisions",
"tags": ["architecture", "storage"],
"snippet": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files...",
"score": 6.41,
"updated": "2026-02-26T14:30:00Z"
}
]Snippets are the first ~150 characters of content, enough to judge relevance without burning context.
memory_recallFetch full content for specific memory IDs. Use after search to load what you actually need.
memory_recall(ids)Parameter | Type | Description |
| string[] | One or more memory IDs from a previous search |
Response
[
{
"id": "550e8400-...",
"namespace": "decisions",
"content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append). JSONL is append-friendly, streamable, human-readable, and grep-compatible.",
"tags": ["architecture", "storage"],
"created": "2026-02-26T14:30:00Z",
"updated": "2026-02-26T14:30:00Z",
"source": "claude-code",
"relations": [],
"ttl": null
}
]memory_deleteSoft-delete a memory. The entry stays in the JSONL file but is excluded from all queries.
memory_delete(id, namespace)memory_list_namespacesList all namespaces with entry counts. No parameters.
[
{ "namespace": "global", "count": 42 },
{ "namespace": "projects/my-app", "count": 17 },
{ "namespace": "decisions", "count": 8 }
]Memento includes a web interface for browsing and managing memories.
npm run adminOpens at http://localhost:3000. Custom port:
MEMENTO_ADMIN_PORT=8080 npm run adminWhat you get:
Dashboard with memory count, namespace count, tag cloud, and recent entries
Namespace browser with drill-down
Full memory viewer with metadata (tags, timestamps, source, TTL, relations)
Create, edit, and delete via forms
BM25 search with namespace and tag filters
Server info page with storage path and disk usage
Memento works best when Claude recalls context at the start of a session and stores important things before finishing. You can enforce this with Claude Code hooks.
~/.claude/hooks/session-start-memento.sh
#!/bin/bash
INPUT=$(cat)
PROJECT=$(basename "$(echo "$INPUT" | jq -r '.cwd // empty')" 2>/dev/null)
if [ -n "$PROJECT" ]; then
echo "[Memento] Search Memento for relevant memories about \"$PROJECT\" before starting work."
else
echo "[Memento] Search Memento for relevant memories before starting work."
fi~/.claude/hooks/stop-memento.sh
#!/bin/bash
STOP_REASON=$(cat | jq -r '.stop_reason // "end_turn"')
if [ "$STOP_REASON" = "end_turn" ]; then
echo "[Memento] Before finishing: did you store significant findings, decisions, or completed work in Memento?"
fichmod +x ~/.claude/hooks/session-start-memento.sh
chmod +x ~/.claude/hooks/stop-memento.sh~/.claude/settings.json{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/session-start-memento.sh",
"timeout": 5
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/stop-memento.sh",
"timeout": 5
}
]
}
]
}
}Add these to permissions.allow so Claude never has to ask for permission:
{
"permissions": {
"allow": [
"mcp__memento__memory_store",
"mcp__memento__memory_recall",
"mcp__memento__memory_search",
"mcp__memento__memory_delete",
"mcp__memento__memory_list_namespaces"
]
}
}The quality of what you get back depends on the quality of what you store.
Front-load the key information. BM25 doesn't care about position, but snippets show the first 150 characters. Put the core fact first.
# Good
Use JSONL for storage. Chosen over SQLite (binary) and single JSON files (can't stream).
# Bad
After a long discussion about storage options, we eventually decided that JSONL would work best.One concept per memory. Separate concerns don't compete for relevance and can be independently recalled.
Always include tags. Memories without tags can only be found by full-text search across everything.
Use namespaces to segment domains. A single global namespace with thousands of entries gets noisy. Scope to projects/my-app or decisions for cleaner results.
~/.memento/
memories/
global.jsonl
decisions.jsonl
procedures.jsonl
projects/
my-app.jsonl
another-project.jsonlEach line in a .jsonl file is one memory entry. Writes are always appends. Updates write a new entry with the same ID, and the loader keeps only the latest version. Deletes write an entry with deleted: true.
Set MEMENTO_HOME to change the base directory.
Variable | Default | Description |
|
| Base directory for all storage |
|
| Port for the admin web UI |
When installed as a Claude Code plugin, three slash commands are available:
Command | Description |
| Search memories and optionally recall full content |
| Store a memory with guided namespace and tag selection |
| Start the admin web UI |
Architecture: Design principles, storage model, search algorithm, context engineering
Schema Reference: Full field reference, dedup rules, response formats
Context Engineering Guide: Progressive disclosure strategy, writing guidelines, anti-patterns, scaling
MIT
Soft-delete a memory by ID. The entry is excluded from future searches. Requires the namespace where the memory is stored.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The memory ID to delete. | |
| namespace | Yes | The namespace containing the memory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that deletion is 'soft' and that the entry is 'excluded from future searches', which are key behavioral traits. However, it does not mention whether the deletion is reversible, what happens to the underlying data, or behavior on missing IDs, but the core behavior is well disclosed.
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?
The description is two sentences, front-loaded with the primary action, and each sentence adds value. There is no redundant information or unnecessary detail. It is exemplary in conciseness.
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?
This is a simple tool with two required parameters and no output schema. The description explains the tool's purpose, effect, and required context. The sibling tools are available for context, and no additional behavioral details seem necessary for correct invocation. The description is complete for this 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 description coverage is 100%, with both 'id' and 'namespace' having clear descriptions. The tool description adds 'Requires the namespace', but this is already evident from the schema. No additional parameter semantics are provided, so the baseline score of 3 is appropriate.
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 clearly states the action 'Soft-delete a memory by ID' and the effect 'excluded from future searches', which distinguishes it from sibling tools like memory_store, memory_search, memory_recall, and memory_list_namespaces. The verb and resource are specific and unambiguous.
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?
The description implies when to use this tool (to soft-delete a memory) and mentions a prerequisite (requires namespace), but it does not explicitly state when not to use it or compare against alternatives. The usage context is clear enough, but no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available namespaces with entry counts. Use this to discover what domains of knowledge exist before searching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'List' clearly implies a read-only operation, and the phrase 'with entry counts' adds insight into the output scope. No side effects or limitations are mentioned, but for a listing tool this is adequate.
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?
The description is two short sentences. The first sentence front-loads the action and result, and the second sentence adds practical usage context. There is no wasted wording.
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 tool with no parameters and no output schema, the description provides sufficient context: it explains what is returned (namespaces with entry counts) and when it should be invoked (before searching). This is complete for the tool's simplicity.
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?
The input schema has zero parameters, so the baseline for this dimension is 4. The description correctly avoids describing parameters since none exist, and it does not need to compensate for any schema gaps.
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 states a specific verb ('List') and resource ('all available namespaces') with the added detail of 'entry counts', making it clear what the tool does. It distinguishes itself from sibling tools (memory_store, memory_search, etc.) by focusing on namespace discovery rather than data manipulation.
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?
The description provides a clear usage context: 'Use this to discover what domains of knowledge exist before searching.' This implies the tool is a preliminary discovery step before using search, though it does not explicitly name the alternative sibling or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full content for specific memory IDs. Use after memory_search to retrieve complete entries for the most relevant results. Only recall what you actually need.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Memory IDs to retrieve full content for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no annotation details since none are provided, so it carries the full burden. It implies read-only behavior via 'Fetch' and hints at potential cost with 'Only recall what you actually need,' but it does not explain what happens with invalid IDs, return structure, or any failure modes. This is minimal but adequate for a simple retrieval tool.
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 short sentences each serve a distinct purpose: stating the action, giving usage context, and providing a best-practice caution. There is no redundancy or filler, and the most important information is front-loaded in the first sentence.
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 tool with one parameter, no annotations, and no output schema, the description covers purpose, usage context, and a cost-conscious guideline. It does not explain the return format or error behavior, but the simplicity of the tool and the clear linkage to memory_search make this sufficiently complete for typical use.
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?
The schema covers 100% of the parameters with a description for 'ids.' The tool description adds contextual usage ('Use after memory_search') but does not deepen parameter semantics beyond the schema—it does not clarify array size limits, duplicate handling, or ID format specifics. This aligns with the baseline for full schema coverage.
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 opens with 'Fetch full content for specific memory IDs,' which clearly states the tool's action (fetch) and target (memory IDs). It also distinguishes itself from siblings by explicitly referencing memory_search as a prior step, making it clear that this tool retrieves details for already-found IDs rather than searching.
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?
The description explicitly says 'Use after memory_search to retrieve complete entries for the most relevant results,' providing a direct when-to-use statement. The instruction 'Only recall what you actually need' adds a concrete exclusionary guideline about avoiding unnecessary fetches. This is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories using BM25 ranking. Returns snippets (first ~150 chars), not full content. Use memory_recall to fetch full content for specific results. Scope searches with namespace and tags for better relevance.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags (AND logic). Only memories with ALL specified tags are scored. | |
| limit | No | Max results to return. Default 10. | |
| query | Yes | Search query. Use specific terms for best results. | |
| namespace | No | Scope to a single namespace. Omit for global search across all namespaces. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that only snippets (~150 chars) are returned, not full content, and mentions the BM25 ranking algorithm. This is valuable behavioral context that helps the agent set expectations.
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?
The description is three sentences long, front-loaded with the primary purpose, and every sentence adds value. It is concise and well-structured with no filler.
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 the tool's simplicity and 100% schema coverage, the description covers the key return behavior (snippets, not full content) and provides a pointer to the complementary tool. There is no output schema, so this disclosure is sufficient for an agent to understand what to expect.
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%, so the schema already explains every parameter (query, limit, namespace, tags). The description briefly mentions namespace and tags for scoping, but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.
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 opens with 'Search memories using BM25 ranking,' which clearly identifies the verb (Search) and resource (memories). It explicitly differentiates from the sibling tool memory_recall by noting this returns snippets, not full 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?
It explicitly instructs to use memory_recall for full content, providing a clear alternative. It also advises scoping with namespace and tags for better relevance, giving practical guidance on when to use this tool effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a memory. Provide an id to update an existing memory. Memories are persistent across sessions and searchable. Write content that is specific, front-loads key information, and covers one concept per entry.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Memory ID. If provided, updates the existing memory with this ID. | |
| ttl | No | ISO 8601 expiry timestamp. After this time the memory is excluded from search. Omit for permanent memories. | |
| tags | No | Labels for filtering. Use lowercase with hyphens. Examples: architecture, preference, procedure, person, bug, learned | |
| content | Yes | The memory text. Be specific and front-load key information. | |
| namespace | No | Target namespace, e.g. "global", "projects/my-app", "people", "decisions". Defaults to "global". | |
| relations | No | IDs of related memories for cross-referencing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses persistence and searchability, which are important behavioral traits, but it does not explain update semantics (e.g., whether fields are merged or replaced) or any side effects. This is a noticeable gap for a write tool.
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?
The description is concise (four sentences, ~35 words) and front-loaded with the core action. Every sentence adds value: purpose, update behavior, persistence/searchability, and content best practices. No filler or repetition.
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 store/upsert tool with six parameters and no output schema, the description covers the essential context: what it does, how to update, persistence, and searchability. It lacks details on return values or edge cases like TTL or namespace handling, but those are documented in the schema. Overall, it's sufficiently complete for the tool's complexity.
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 description coverage is 100%, so the schema already documents all six parameters. The description adds content-writing guidance ('specific, front-loads key information, one concept per entry') that complements the schema but does not substantially enhance understanding of parameter semantics beyond 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?
Uses a specific verb pair 'create or update' with resource 'a memory', and the tool's name clearly indicates the write operation. It contrasts with siblings (search, recall, delete, list) by being the only write tool, and the description reinforces this.
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?
The description gives clear context that memories are persistent and searchable, implying this tool is for storing information. However, it does not explicitly mention alternatives like memory_search or memory_delete, nor does it state when not to use it. Still, the purpose is unambiguous and the content guidance is useful for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: store creates/updates, search finds, recall retrieves full content, delete removes, and list_namespaces discovers domains. No overlapping functionality exists, and the descriptions explicitly differentiate between search and recall.
All tool names follow a consistent memory_verb pattern (store, search, recall, delete, list_namespaces). This makes the set predictable and easy to navigate.
With 5 tools, the server is well-scoped for a memory management system. Each tool addresses a distinct operation without unnecessary redundancy or bloat.
The tool set covers the full lifecycle of memory management: create/update (memory_store), read (memory_recall), search (memory_search), delete (memory_delete), and discovery (memory_list_namespaces). There are no obvious gaps or dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent, portable memory for AI assistants — your private memory graph, from 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/Kotrotsos/memento-core'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
