Skip to main content
Glama
iamjpsharma

MCP Memory Server

by iamjpsharma
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Fremem (formerly MCP Memory Server)

License Python Release

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:

  1. Local IDE (stdio): Used by Windsurf/Cursor (default).

  2. 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 --help

Configure 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 where fremem will 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-data or ~/.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_http

Access 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 fremem

The 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-thaama

  • project-openclaw

  • project-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 pipx installed the binary to a location not in your system's PATH (e.g., ~/.local/bin).

    • Fix: Run pipx ensurepath and 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 pwd to ensure your absolute paths in mcp_config.json are 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-v2 model (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 fremem

If 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 command

  • Project 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 tools
memory_addB

Add a new memory fragment/document to the project's vector store.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesUnique ID for this memory fragment (to support updates)
metaNoOptional JSON metadata
textYesThe text content to verify
project_idYesUnique identifier for the project scope

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It only states 'add' without disclosing whether it overwrites on duplicate ID, side effects, permissions needed, or what happens if the project doesn't exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and to the point. It could be slightly more informative without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, 3 required, a nested object, and no output schema, the description is too sparse. It omits important details such as return value, duplicate handling, and project existence behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all parameters described), so baseline is 3. The description does not add additional meaning beyond the schema, e.g., the update behavior implied by the 'id' parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Add') and the resource ('memory fragment/document') with context ('to the project's vector store'). It distinguishes itself from sibling tools that perform deletion, listing, reset, search, or stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for adding new memories, but it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it or provide any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_delete_sourceB

Delete all memories associated with a specific file source.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesThe exact source (e.g., file path) to delete.
project_idYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It only mentions deletion but does not describe traits like irreversibility, required permissions, error behavior, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words, efficiently conveying the tool's action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema and it's a destructive tool, the description lacks completeness: it does not explain return values, prerequisites, or what constitutes a valid source. It serves as a minimal definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%. The description adds meaning to the 'source' parameter (exact source like file path), but does not mention 'project_id' or clarify its relationship to the deletion scope. Partially compensates for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (delete), resource (memories), and condition (associated with a specific file source). It distinguishes from sibling tools like memory_add or memory_search, which do not involve deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like memory_reset (which might delete all memories) or when not to use it. The description only states what it does.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_list_sourcesB

List all files/sources ingested for a project.

ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYesProject ID

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It does not disclose behavioral traits such as whether the operation is read-only, pagination, or performance implications. The description simply states what it does without additional transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the key action. It is efficient with no wasted words, though it could include more useful information without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity and full schema coverage, the description is minimally adequate. However, it lacks any information about the output format (no output schema), which is important for a list tool. Sibling tools are not compared.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter project_id with a description ('Project ID'), so schema_description_coverage is 100%. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List all files/sources ingested for a project.' It uses a specific verb ('list') and resource ('files/sources'), and distinguishes it from sibling tools like memory_add and memory_delete_source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., memory_search). The description does not mention prerequisites, context, or 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.

memory_resetC

Reset (clear) all memories for a project.

ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description only says 'clear all memories', implying destructive action but lacking details on irreversibility, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks necessary detail. It is front-loaded but insufficient for full understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's destructive nature and no output schema, the description should explain what 'memories' are and the impact of resetting; it fails to provide this context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'project_id' is not explained in the description; schema coverage is 0%, so the description adds no semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'reset' and the resource 'all memories for a project', distinguishing it from sibling tools that add, delete, search, or stat memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like memory_delete_source or memory_add; no mention of prerequisites or potential issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_statsC

Get statistics for a project's memory (chunk count).

ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only says 'get statistics' implying read-only. No disclosure of return format, side effects, permissions, or rate limits. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and to the point, but it is under-specified given the tool's context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one required parameter and no output schema, the description lacks return value details, error conditions, and context about the chunk count statistic. Incomplete for effective usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description provides no additional meaning for the project_id parameter beyond the schema's type and required flag. No format, source, or usage hints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'Get' and resource 'statistics for a project's memory (chunk count)', clearly indicating it retrieves memory usage statistics. It distinguishes from sibling tools like memory_add or memory_reset which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like memory_list_sources or memory_search. No prerequisites or context for usage are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.2.1
    • First observedmemory_add
    • First observedmemory_delete_source
    • First observedmemory_list_sources
    • First observedmemory_reset
    • First observedmemory_search
    • First observedmemory_stats
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: add, delete by source, list sources, reset, search, and stats. No overlapping functionality between them.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'memory_' prefix, e.g., memory_add, memory_delete_source. No mixing of conventions.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Memento

    iAchilles
    A
    license
    A
    quality
    C
    maintenance
    A local, fully-offline MCP memory server that enables persistent storage and retrieval of information using SQLite with both keyword and semantic vector search capabilities.
    10
    19 npm
    13
    MIT

  • Vector Memory MCP Server

    aeriondyseti
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides 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.
    81 npm
    5
    MIT

  • AIVectorMemory

    Edlineas
    A
    license
    B
    quality
    D
    maintenance
    MCP 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.
    9
    25 PyPI
    91
    Apache 2.0

  • CoreMemory-MCP

    michaelfeng
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides a local, persistent long-term memory service for MCP-compatible AI agents, enabling them to store, search, and recall information across sessions.
    1
    GPL 3.0