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., "@Memorious MCP store my favorite coffee order as large oat milk latte with two shots"
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.
A 100% local & private semantic memory MCP (Model Context Protocol) server for AI assistants. Built with ChromaDB for vector similarity search and FastMCP 2. Runs entirely locally - no data ever leaves your machine.
memorious-mcp provides AI assistants with long-term memory capabilities through three core operations: store, recall, and forget. It uses ChromaDB's vector database to enable semantic similarity search, allowing assistants to retrieve relevant memories even when the exact wording differs from the original storage. All processing and storage happens locally on your machine - no data ever leaves your machine, ensuring complete privacy and security.
Related MCP server: MCPMem
š 100% Local & Private: All data processing and storage happens on your machine - nothing goes to the cloud
š¾ Persistent Memory: Data persists across sessions using ChromaDB's disk-based storage
š Semantic Search: Vector embeddings enable similarity-based memory retrieval
ā” Simple API: Three intuitive tools for memory management
š FastMCP Integration: Built on FastMCP for efficient MCP server implementation
šÆ Canonical Key Design: Optimized for short, embedding-friendly keys (1-5 words)
š Folder Scoped Storage: Per-project memory isolation.
š Gap in the MCP Ecosystem: Despite the growing popularity of memory MCP servers, there wasn't an existing memory server that combines both semantic similarity search and complete file based folder scoped local storage. Most memory solutions either:
āļø Require cloud services and external API calls (compromising privacy) for either embeddings or storage or both
š¤ Only support exact key-value matching (no semantic understanding)
š Don't support folder scoped local storage
Personal Assistant Memory: Remember user preferences, habits, and personal information
Context Preservation: Maintain conversation context across sessions
Knowledge Management: Store and retrieve project-specific information
Personalization: Enable AI assistants to provide personalized responses based on stored preferences
Privacy-First AI: Keep sensitive personal data local while still having persistent memory
Folder-Scoped AI Agents: Perfect for VS Code Copilot Chat Modes and Claude Code agents with per-project memory isolation
Make sure you have uv and its its uvx command installed first.
Add to your MCP client configuration:
{
"mcpServers": {
"memorious": {
"command": "uvx",
"args": ["memorious-mcp"]
}
}
}uv syncFor development/local installation:
{
"mcpServers": {
"memorious": {
"command": "uv",
"args": ["run", "memorious-mcp"],
"cwd": "/path/to/memorious-mcp"
}
}
}storeStore facts, preferences, or information with short canonical keys optimized for vector similarity.
Parameters:
key (string): Short, canonical key (1-5 words, space-separated)
value (string): The actual information to store
recallRetrieve stored memories using semantic similarity search.
Parameters:
key (string): Query key for similarity search
top_k (int, default: 3): Maximum number of results to return
forgetDelete memories matching a query key.
Parameters:
key (string): Query key to find memories to delete
top_k (int, default: 3): Number of nearest matches to consider
To add memorious-mcp to Claude CLI, use the following commands:
# Add the MCP server using uvx (recommended)
claude mcp add memorious-mcp uvx memorious-mcp
# Alternative: for development/local installation
claude mcp add memorious-mcp uv run --project <memorious_mcp_src> memorious-mcpYou can then list your configured MCP servers:
claude mcp listAnd remove the server if needed:
claude mcp remove memorious-mcpstore(key: str, value: str) -> {"id": str}
recall(key: str, top_k: int = 3) -> {"results": [...]} where each result includes id, key, value, distance, timestamp
forget(key: str, top_k: int = 3) -> {"deleted_ids": [...]}
Run tests with:
# Using uv
uv run python -m pytest tests/ -v
# Or if pytest is available globally
pytest tests/ -vBackend: ChromaDB with persistent disk storage
Embeddings: Uses ChromaDB's default embedding function (local processing)
Storage Location: ./.memorious directory (configurable)
Python Version: Requires Python ā„3.12
License: MIT
Privacy: No network requests, no cloud dependencies, all data stays local
The project follows the standard Python package layout:
memorious-mcp/
āāā src/
ā āāā memorious_mcp/
ā āāā __init__.py
ā āāā main.py # MCP server entry point
ā āāā backends/
ā āāā __init__.py
ā āāā memory_backend.py # Abstract base class
ā āāā chroma_backend.py # ChromaDB implementation
āāā tests/
ā āāā test_chroma_backend.py # Integration tests
āāā pyproject.toml # Package configuration
āāā README.mdThe server is designed for local/CLI integrations using stdio transport, making it suitable for personal AI assistants and development workflows where privacy and data security are paramount.
ā ļø Important Security Considerations
While your data is 100% safe and private because it never leaves your local machine, you should still exercise caution about what you store:
Data is stored unencrypted: All stored data is persisted to disk in unencrypted format in the .memorious directory
Avoid storing secrets: Do NOT store passwords, API keys, private keys, personal identification numbers, financial information, or any other sensitive credentials
Local file access: Anyone with access to your machine and the .memorious directory can read all stored memories
Exercise caution: While the MCP server warns the client LLM to avoid storing sensitive information, you should not rely solely on this safeguard
Backup considerations: Be mindful when backing up or syncing directories containing .memorious folders
Contributions are welcome. Open a PR with tests.
Delete stored memories that match a query key.
IMPORTANT: Deletion operates on short, canonical keys. The LLM MUST issue forget calls using the same concise, embedding-optimized, space-separated key style used to create memories (otherwise relevant memories may not be found). Prefer 1ā5 words separated by spaces when requesting deletions.
This tool SHOULD be called by the LLM when the user explicitly requests that certain stored information be forgotten or removed (for example: "forget that I live in Paris") or when the assistant decides a memory must be purged because it is incorrect or sensitive.
Parameters:
key: concise, canonical, space-separated query text used to find candidate memories to delete.
top_k: number of nearest matches to consider for deletion.
Behavior:
Deletion is irreversible; the LLM should confirm with the user when intent is ambiguous before invoking this tool.
The tool returns deleted_ids for the memories that were removed.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| top_k | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses irreversibility, the need to confirm ambiguous intent, return format (deleted_ids), and the critical key-style constraint. This goes well beyond basic 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 well-structured with clear sections and front-loaded purpose. Each sentence serves a purpose, and the IMPORTANT note is strategically placed. No unnecessary 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?
Despite no annotations or output schema, the description covers purpose, usage, parameters, behavior, and return value. It fully addresses the tool's complexity and compensates for missing structured information.
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 0%, so the description fully compensates by explaining both parameters: 'key' as concise canonical query text and 'top_k' as number of nearest matches. This adds meaningful context beyond the raw 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 clearly states the tool deletes stored memories matching a query key, using a specific verb and resource. It distinguishes itself from sibling tools (store, recall) as the deletion counterpart.
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 explicit scenarios for when to use the tool (user requests forgetting, assistant purging incorrect/sensitive data) with concrete examples. It does not explicitly mention alternatives like 'recall' for retrieval, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve stored memories relevant to a query key.
IMPORTANT: To get reliable results the LLM MUST query with the same short, canonical, embedding-optimized keys used at store time. Keys should be compact (1ā5 words, space-separated) and represent the core concept ā avoid long descriptive queries. If the current user utterance is verbose, the LLM should first map or canonicalize it to an appropriate short key before calling this tool (for example map "I really like listening to jazz music" -> "likes jazz").
This tool SHOULD be called by the LLM when it needs to fetch previously stored facts, personal details, or preferences to inform a response or provide personalized behavior (for example: to recall a user's favorite cuisine before making restaurant suggestions).
Parameters:
key: concise, embedding-friendly, space-separated query text used for similarity search.
top_k: maximum number of nearest memories to return.
Returns a dict with results (memory items including stored value).
If nothing matches, results is empty.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| top_k | No |
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 the critical canonical-key matching requirement, the return format (dict with 'results'), and the empty-result behavior. It does not cover permissions, side effects, or error cases, but for a simple retrieval tool it is fairly transparent.
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 a bit longer than necessary but well-structured into an overview, an IMPORTANT note, usage guidance, parameter descriptions, and return info. Every section earns its place, with no redundant fluff.
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?
The tool is simple with only two parameters and no output schema. The description covers return value shape, empty result behavior, and the crucial key canonicalization guidance. It could be more explicit about what's inside each memory item, but 'including stored value' is sufficient for a retrieve-by-key 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 0%, so the description must explain parameters. It does so thoroughly: 'key' is described as 'concise, embedding-friendly, space-separated query text used for similarity search,' and 'top_k' as 'maximum number of nearest memories to return.' It even provides a mapping example, fully compensating for the schema gap.
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 'Retrieve stored memories relevant to a query key,' which is a specific verb+resource+query. It clearly distinguishes from sibling tools 'store' and 'forget' by focusing on retrieval.
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 states 'This tool SHOULD be called by the LLM when it needs to fetch previously stored facts, personal details, or preferences,' giving clear usage context. However, it does not explicitly mention when not to use it or contrast with store/forget, so it misses the 'when-not' part.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a user's fact, piece of information, or preference for later recall.
CRITICAL SECURITY WARNING: NEVER EVER store secrets, passwords, API keys, authentication tokens, private keys, or any other sensitive credentials. This storage is NOT secure and should only be used for non-sensitive information like preferences, facts, and general user data.
IMPORTANT: key MUST be short, canonical, and optimized for
embedding/vector similarity lookups. Prefer 1ā5 words separated by spaces
(for example: "likes jazz", "pref cuisine italian", "lives in paris").
Do NOT use long sentences or paragraphs as keys ā put long text into
value instead.
This tool SHOULD be called by the LLM whenever the user states a fact, personal detail, or stable preference that the assistant is expected to remember.
Guidelines for the LLM:
Call this tool for user-expressed facts, identity details, or explicit preferences that will be useful later.
Use key as a short, consistent, space-separated descriptor across
related memories to improve retrieval quality (canonicalize synonyms
where possible).
Use value for the full text of the fact or preference to be stored
and returned on recall; include any extra context inside value.
Privacy: avoid storing highly sensitive data (passwords, social security numbers, bank details) unless the user explicitly requests secure storage and consents.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| value | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly warns that the storage is NOT secure, advises against storing secrets, and describes the intended use for non-sensitive information. This goes beyond a basic 'store' explanation and discloses important behavioral constraints.
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?
Although the description is longer than typical, every section earns its place: security warning, key formatting rules, usage guidelines, and privacy note. It is well-structured with clear headings and bullet points, making it easy to scan without unnecessary verbosity.
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 (two string parameters, no output schema, no annotations), the description is fully complete. It covers the tool's purpose, when to use it, how to format parameters, and important security caveats. Nothing critical is missing for safe and correct 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?
Schema description coverage is 0%, but the description compensates excellently. It explains exactly how to format 'key' (short, canonical, 1-5 words, space-separated, with examples) and how to use 'value' (full text, include extra context). This adds significant meaning beyond the bare schema properties.
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 explicitly states the tool stores a user's fact, piece of information, or preference for later recall. It uses a specific verb ('store') and resource ('user's fact...') and clearly distinguishes itself from the sibling tools 'recall' and 'forget' by focusing on the storage action.
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 explicit when-to-use guidance: 'This tool SHOULD be called by the LLM whenever the user states a fact, personal detail, or stable preference that the assistant is expected to remember.' It also gives clear exclusions (do not store sensitive credentials) and alternative handling, which fully covers usage context.
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.
v0.0.2forgetrecallstoreScored across 3 tools
The three tools have clearly distinct purposes: store creates a memory, recall retrieves memories, and forget deletes memories. There is no overlap or ambiguity between them.
All tool names are single-word imperative verbs (store, recall, forget) following a consistent and predictable pattern. This makes the tool set easy to understand and use.
Three tools is well-scoped for a memory management server, covering the essential operations without redundancy or bloat. Each tool earns its place.
The tool set provides create, read, and delete operations for memories, covering the core lifecycle. The only notable gap is the absence of an explicit update operation, though store may implicitly handle this by overwriting existing keys.
Long-term memory for AI assistants. Hybrid retrieval, query expansion, auto-topics.
Long-term memory for AI assistants. Isolated per-user storage, recall across conversations.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
