MCP Memory Server
Provides persistent vector memory storage and semantic search capabilities for the Windsurf editor, allowing for project-specific context retrieval and documentation ingestion.
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., "@MCP Memory Server search for architectural decisions in project-thaama"
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.
Fremem (formerly MCP Memory Server)
A persistent vector memory server for Windsurf, VS Code, and other MCP-compliant editors.
π Philosophy
Privacy-first, local-first AI memory: Your data stays on your machine.
No vendor lock-in: Uses open standards and local files.
Built for MCP: Designed specifically to enhance Windsurf, Cursor, and other MCP-compatible IDEs.
Related MCP server: Vector Memory MCP Server
βΉοΈ Status (v0.2.0)
Stable:
β Local MCP memory with Windsurf/Cursor
β Multi-project isolation
β Ingestion of Markdown docs
Not stable yet:
π§ Auto-ingest (file watching)
π§ Memory pruning
π§ Remote sync
Note: There are two ways to run this server:
Local IDE (stdio): Used by Windsurf/Cursor (default).
Docker/Server (HTTP): Used for remote deployments or Docker (exposes port 8000).
π₯ Health Check
To verify the server binary runs correctly:
# From within the virtual environment
python -m fremem.server --helpβ Quickstart (5-Minute Setup)
There are two ways to set this up: Global Install (recommended for ease of use) or Local Dev.
Option A: Global Install (Like npm -g)
This method allows you to run fremem from anywhere without managing virtual environments manually.
1. Install pipx (if not already installed):
MacOS (via Homebrew):
brew install pipx
pipx ensurepath
# Restart your terminal after this!Linux/Windows: See pipx installation instructions.
2. Install fremem:
# Install from PyPI
pipx install fremem
# Verify installation
fremem --helpConfigure Windsurf / VS Code:
Since pipx puts the executable in your PATH, the config is simpler:
{
"mcpServers": {
"memory": {
"command": "fremem",
"args": [],
"env": {
"MCP_MEMORY_PATH": "/Users/YOUR_USERNAME/mcp-memory-data"
}
}
}
}Note on
MCP_MEMORY_PATH: This is wherefrememwill store its persistent database. You can point this to any directory you like (checks locally or creating it if it doesn't exist). We recommend something like~/mcp-memory-dataor~/.fremem-data. It must be an absolute path.
Option B: Local Dev Setup
1. Clone and Setup
git clone https://github.com/iamjpsharma/fremem.git
cd fremem
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies AND the package in editable mode
pip install -e .2. Configure Windsurf / VS Code (Local Dev)
Add this to your mcpServers configuration (e.g., ~/.codeium/windsurf/mcp_config.json):
Note: Replace /ABSOLUTE/PATH/TO/fremem with the actual full path to the cloned directory.
{
"mcpServers": {
"memory": {
"command": "/ABSOLUTE/PATH/TO/fremem/.venv/bin/python",
"args": ["-m", "fremem.server"],
"env": {
"MCP_MEMORY_PATH": "/ABSOLUTE/PATH/TO/fremem/mcp_memory_data"
}
}
}
}In local dev mode, it's common to store the data inside the repo (ignored by git), but you can use any absolute path.
π Usage
0. HTTP Server (New)
You can run the server via HTTP (SSE) if you prefer:
# Run on port 8000
python -m fremem.server_httpAccess the SSE endpoint at http://localhost:8000/sse and send messages to http://localhost:8000/messages.
π³ Run with Docker
To run the server in a container:
# Build the image
docker build -t fremem .
# Run the container
# Mount your local data directory to /data inside the container
docker run -p 8000:8000 -v $(pwd)/mcp_memory_data:/data frememThe server will be available at http://localhost:8000/sse.
1. Ingestion (Adding Context)
Use the included helper script ingest.sh to add files to a specific project.
# ingest.sh <project_name> <file1> <file2> ...
# Example: Project "Thaama"
./ingest.sh project-thaama \
docs/architecture.md \
src/main.py
# Example: Project "OpenClaw"
./ingest.sh project-openclaw \
README.md \
CONTRIBUTING.mdπ‘ Project ID Naming Convention
It is recommended to use a consistent prefix for your project IDs to avoid collisions:
project-thaamaproject-openclawproject-myapp
2. Connect in Editor
Once configured, the following tools will be available to the AI Assistant:
memory_search(project_id, q, filter=None): Semantic search. Supports metadata filtering (e.g.,filter={"type": "code"}). Returns distance scores.memory_add(project_id, id, text): Manual addition.memory_list_sources(project_id): specific files ingested.memory_delete_source(project_id, source): Remove a specific file.memory_stats(project_id): Get chunk count.memory_reset(project_id): Clear all memories for a project.
The AI will effectively have "long-term memory" of the files you ingested.
π Troubleshooting
"fremem: command not found" after installing:
This means
pipxinstalled the binary to a location not in your system's PATH (e.g.,~/.local/bin).Fix: Run
pipx ensurepathand restart your terminal.Manual Fix: Add
export PATH="$PATH:$HOME/.local/bin"to your shell config (e.g.,~/.zshrc).
"No MCP server found" or Connection errors:
Check the output of
pwdto ensure your absolute paths inmcp_config.jsonare 100% correct.Ensure the virtual environment (
.venv) is created and dependencies are installed.
"Wrong project_id used":
The AI sometimes guesses the project ID. You can explicitly tell it: "Use project_id 'project-thaama'".
Embedding Model Downloads:
On the first run, the server downloads the
all-MiniLM-L6-v2model (approx 100MB). This may cause a slight delay on the first request.
ποΈ Uninstalling
To remove fremem from your system:
If installed via pipx (Global):
pipx uninstall frememIf installed locally (Dev): Just delete the directory.
π Repo Structure
/
βββ src/fremem/
β βββ server.py # Main MCP server entry point
β βββ ingest.py # Ingestion logic
β βββ db.py # LanceDB wrapper
βββ ingest.sh # Helper script
βββ requirements.txt # Top-level dependencies
βββ pyproject.toml # Package config
βββ mcp_memory_data/ # Persistent vector storage (gitignored)
βββ README.mdπΊοΈ Roadmap
β Completed (v0.1.x)
Local vector storage (LanceDB)
Multi-project isolation
Markdown ingestion
PDF ingestion
Semantic chunking strategies
Windows support + editable install fixes
HTTP transport wrapper (SSE)
Fix resource listing errors (clean MCP UX)
Robust docs + 5-minute setup
Multi-IDE support (Windsurf, Cursor-compatible MCP)
π Near-Term (v0.2.x β Production Readiness)
π§ Memory Governance
List memory sources per project
Delete memory by source (file-level deletion)
Reset memory per project
Replace / reindex mode (prevent stale chunks)
Memory stats (chunk count, last updated, size)
π― Retrieval Quality
Metadata filtering (e.g., type=decision | rules | context)
Similarity scoring in results
Hybrid search (semantic + keyword)
Return evidence + similarity scores with search results
Configurable top_k defaults per project
βοΈ Dev Workflow
Auto-ingest on git commit / file change
mcp-memory init <project-id>bootstrap commandProject templates (PROJECT_CONTEXT.md, DECISIONS.md, AI_RULES.md)
π§ Advanced RAG (v0.3.x β Differentiators)
Hierarchical retrieval (summary-first, detail fallback)
Memory compression (old chunks β summaries)
Temporal ranking (prefer newer decisions)
Scoped retrieval (planner vs coder vs reviewer agents)
Query rewrite / expansion for better recall
π’ Team / SaaS Mode (Optional)
Philosophy: Local-first remains the default. SaaS is an optional deployment mode.
π Auth & Multi-Tenancy
Project-level auth (API keys or JWT)
Org / team separation
Audit logs for memory changes
βοΈ Remote Storage Backends (Pluggable)
S3-compatible vector store backend
Postgres / pgvector backend
Sync & Federation (Local β Remote)
π« Non-Goals
β No mandatory cloud dependency
β No vendor lock-in
β No chat history as βmemoryβ by default (signal > noise)
β No model fine-tuning
Available Tools
6 toolsmemory_addB
Add a new memory fragment/document to the project's vector store.
Inputs: id (required), text (required), project_id (required), meta.
memory_delete_sourceB
Delete all memories associated with a specific file source.
Inputs: source (required), project_id (required).
memory_list_sourcesB
List all files/sources ingested for a project.
Inputs: project_id (required).
memory_resetC
Reset (clear) all memories for a project.
Inputs: project_id (required).
memory_searchA
Search the semantic memory for a specific project using a natural language query.
Inputs: q (required), project_id (required), k, filter.
memory_statsC
Get statistics for a project's memory (chunk count).
Inputs: project_id (required).
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 clearly distinct purpose: add, delete by source, list sources, reset, search, and stats. No overlapping functionality between them.
All tools follow a consistent verb_noun pattern with 'memory_' prefix, e.g., memory_add, memory_delete_source. No mixing of conventions.
6 tools is well-scoped for a memory management server covering core CRUD-like operations plus search and stats. Not too few nor too many.
Covers add, delete by source, list sources, search, and stats. Lacks individual memory item update or delete, but for vector stores these are less critical. Minor gap.
Maintenance
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseAqualityCmaintenanceA local, fully-offline MCP memory server that enables persistent storage and retrieval of information using SQLite with both keyword and semantic vector search capabilities.108 npm13MIT
- AlicenseNot gradedqualityBmaintenanceProvides local vector-based semantic memory storage for AI assistants to persist context and decisions across sessions using local embeddings and LanceDB. It enables private semantic search and session handoff capabilities to maintain long-term project context.53 npm4MIT
- AlicenseBqualityDmaintenanceMCP server that provides cross-session persistent memory for AI coding assistants using local vector database and semantic search, enabling automatic recall of project context, issues, and tasks.997 PyPI93Apache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides a local, persistent long-term memory service for MCP-compatible AI agents, enabling them to store, search, and recall information across sessions.1GPL 3.0