memorious

memorious-mcp is a private, local memory MCP server that provides long-term memory capabilities for AI assistants. It uses ChromaDB as a persistent vector store to enable semantic recall, and exposes three core tools: store, recall, and forget. You can store short, embedding-friendly keys (1-5 words) with associated values, retrieve memories via semantic similarity queries, and prune memories by matching keys. All processing happens locally, ensuring privacy and data control. The server is designed to integrate with standard MCP clients and is compatible with FastMCP 2, making it suitable for VS Code Copilot-like plugins or Claude CLI workflows that manage per-project memory isolation.

To interact with memorious, run the MCP server using uvx (or uv for development) and then call the tools via your MCP client: use store(key, value) to persist information, recall(key, top_k) to fetch the most semantically related memories, and forget(key, top_k) to delete memories that match a query. The system stores data on disk under a local .memorious directory and keeps all data on your machine. For per-project memory isolation, you can run separate memorious instances per project and point your tooling to the appropriate memory store.

Prerequisites:

• Python 3.12 or newer
• uv (and uvx) installed on your system for local MCP operation
• Local disk accessible storage for memory data (default: .memorious)

Install steps:

1. Install uv/uvx if you haven’t already. For example, follow the uv installation guide at https://docs.astral.sh/uv/ and ensure uv and uvx are available on your PATH.

2. Install the memorious MCP server using uvx (recommended):

uvx memorious-mcp

This registers the memorious-mcp server for MCP clients and prepares the local environment.

3. Alternatively, for development/local installation, you can install and run directly with uv:

uv run memorious-mcp

This assumes you have the memorious-mcp project sources available locally, e.g., at /path/to/memorious-mcp, and your command should include a working directory:

uv run memorious-mcp --project /path/to/memorious-mcp

4. If you are configuring Claude or another MCP client, add memorious to your client settings. Example (via uvx):

{
  "mcpServers": {
    "memorious": {
      "command": "uvx",
      "args": ["memorious-mcp"]
    }
  }
}

5. Start the server in your environment and connect your MCP client. The server uses the local disk storage under the default ".memorious" directory for persistence; you can customize storage location via configuration if needed later.

Tips and caveats:

• Privacy: All data is stored locally. Data is stored unencrypted on disk in the .memorious directory. Do not store secrets or sensitive credentials in memory keys or values.
• Disk storage: Because memory is persisted on disk, ensure you have sufficient space for your memory set; large datasets will consume disk space over time.
• Keys: Use short, canonical keys (1-5 words) to optimize embedding-based retrieval efficiency.
• Environment: If you run multiple per-project instances, consider isolating each memorious instance with separate .memorious directories and distinct working directories to avoid cross-contamination of memories.
• Version compatibility: Ensure Python 3.12+ compatibility with your tooling and the UV runtime you choose (uvx vs uv).
• Testing: The repository includes integration tests for the chroma backend; consider running tests during development to validate memory operations.