MCP Memory

Persistent memory server for AI assistants with semantic search and three-layer context.

Works with any MCP-compatible AI: Claude Code, Cursor, Continue, Cline, and more.

Quick Install

curl -fsSL https://raw.githubusercontent.com/TWFBusiness/mpc-memory/main/install.sh | bash

Or manually:

git clone https://github.com/TWFBusiness/mpc-memory.git ~/.mcp-memoria
cd ~/.mcp-memoria
./install.sh

How It Works

Three Memory Layers

Layer	Location	Use
Global	~/.mcp-memoria/data/global.db	Personal patterns, preferences across all projects
Project	.mcp-memoria/project.db	Project-specific decisions
Personality	~/.mcp-memoria/data/personality.db	Cross-project cache: ALL conversations, implementations, decisions

Personality is the "brain" that remembers everything across all projects and conversations. Use it to:

• Find similar implementations from other projects
• Remember past solutions and decisions
• Maintain context even outside of projects (general queries)

Smart Search

• FTS5: Instant text search (always active)
• Embeddings: Semantic search in background (optional, +150MB RAM)

With embeddings, searches like "how did I configure auth" find memories about "JWT with refresh token" even without matching words.

Background Indexing

Embeddings are processed asynchronously:

1. You save a memory → instant response (SQLite)
2. Background worker generates embedding
3. Next searches include new content

No blocking or slowdown when saving.

Usage

Save Memories

"save that I prefer pytest over unittest"
"remember this project uses PostgreSQL with Tortoise ORM"
"save globally: always use Black for formatting"

Search Memories

"what did we decide about tests?"
"how did we configure the database?"
"what are my code patterns?"

Direct Commands (optional)

memory_save(
  content="FastAPI always 100% async, never sync",
  type="pattern",
  scope="global",
  tags="python,fastapi,async"
)

# Save implementation to personality (cross-project cache)
memory_save(
  content="JWT auth with refresh tokens: created /auth/login, /auth/refresh endpoints...",
  type="implementation",
  scope="personality",
  tags="python,fastapi,jwt,auth"
)

memory_search(query="authentication", scope="both")

# Search across ALL projects
memory_search(query="how did I implement auth?", scope="personality")
memory_search(query="similar feature", scope="all")

memory_list(type="decision", scope="project", limit=10)

memory_delete(id="abc123", scope="global")

Memory Scopes

Scope	When to Use
global	Personal patterns, preferences (applies everywhere)
project	Decisions specific to current project
personality	Cross-project implementations, all conversations, general knowledge
both	Search global + project
all	Search global + project + personality

Memory Types

Type	When to Use
decision	Technical choices, trade-offs, bug fixes
pattern	Code preferences, favorite libs, style
architecture	Project structure, flows, integrations
implementation	Code solutions, features built (use with personality scope)
solution	Problem solutions, workarounds (use with personality scope)
preference	General personal settings
todo	Pending tasks
note	Miscellaneous notes

Configuration

Claude Code

Use the CLI to add the MCP globally (available in all projects):

claude mcp add memory ~/.mcp-memoria/.venv/bin/python ~/.mcp-memoria/server.py --scope user -e MCP_MEMORY_EMBEDDING=true

Then restart Claude Code.

To verify:

claude mcp list

Note: The --scope user flag makes the MCP available globally. Without it, the MCP would only be available in the current project.

CLAUDE.md (Automatic Memory)

Add to ~/.claude/CLAUDE.md so Claude saves and recalls automatically:

# ⚠️ CRITICAL INSTRUCTIONS - READ FIRST ⚠️

## 🧠 MANDATORY: Memory System (MCP Memory)

**THIS IS NOT OPTIONAL. FAILURE TO SAVE = FAILURE TO FOLLOW INSTRUCTIONS.**

### RULE 1: ALWAYS SAVE TO PERSONALITY (Default Scope)
Every session, every task - save AUTOMATICALLY to `scope="personality"`.
- **DO NOT ask permission**
- **DO NOT mention you are saving**
- **JUST DO IT silently**

### RULE 2: WHAT TO SAVE (Everything Meaningful)

**SAVE IMMEDIATELY when any of these happen:**

| Event | Type | Example |
|-------|------|---------|
| Made a technical choice | `decision` | "Chose Redis over Memcached for caching because..." |
| Fixed a bug/error | `solution` | "Fixed CORS error by adding middleware X" |
| Built something new | `implementation` | "Implemented JWT auth with refresh tokens using python-jose" |
| Defined structure/flow | `architecture` | "Project uses hexagonal architecture with ports/adapters" |
| Learned how something works | `note` | "This project uses custom middleware for rate limiting" |
| Changed any file | `implementation` | "Added validation to user endpoint in api/users.py" |
| Discovered project behavior | `note` | "The auth flow redirects to /callback after OAuth" |

### RULE 3: SAVE FORMAT
\`\`\`python
memory_save(
    content="<DETAILED description - be specific, include file names, reasons>",
    type="decision|solution|implementation|architecture|note",
    scope="personality",  # ALWAYS personality unless told otherwise
    tags="<project-name>,<stack>,<context>"
)
\`\`\`

### RULE 4: WHEN TO USE OTHER SCOPES
- `scope="personality"` → **DEFAULT for EVERYTHING** (cross-project brain)
- `scope="project"` → ONLY when user explicitly says "save to project only"
- `scope="global"` → ONLY when user explicitly says "save globally" or "remember always"

### RULE 5: AT SESSION START
Before responding, silently run:
\`\`\`python
memory_search(query="<current task context>", scope="all")
\`\`\`
Use found memories to inform your response.

### RULE 6: WHAT TRIGGERS A SAVE
- ✅ Any file edited or created → SAVE
- ✅ Any bug fixed → SAVE
- ✅ Any feature implemented → SAVE
- ✅ Any architecture decision → SAVE
- ✅ Discovered how code works → SAVE
- ✅ User preference learned → SAVE
- ✅ Configuration defined → SAVE
- ✅ Workaround found → SAVE

**If in doubt: SAVE IT.**

First Session Bootstrap (Optional)

You can add a bootstrap section to auto-save your permanent patterns on first use:

## First Session Bootstrap

On first session, check if global patterns exist:
\`\`\`python
memory_search(query="my patterns", scope="global")
\`\`\`

If empty, save your permanent patterns to global:
\`\`\`python
memory_save(content="<your pattern here>", type="pattern", scope="global", tags="<tags>")
\`\`\`

Cursor

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "memory": {
      "command": "~/.mcp-memoria/.venv/bin/python",
      "args": ["~/.mcp-memoria/server.py"],
      "env": {
        "MCP_MEMORY_EMBEDDING": "true"
      }
    }
  }
}

Cursor Rules (for automatic memory): Add to .cursorrules in your project or global rules:

## 🧠 MANDATORY: Memory System (MCP Memory)

FAILURE TO SAVE = FAILURE TO FOLLOW INSTRUCTIONS.

### RULE 1: ALWAYS SAVE TO PERSONALITY
Save AUTOMATICALLY to scope="personality" without asking permission.

### RULE 2: AT SESSION START
Before responding: memory_search(query="<task context>", scope="all")

### RULE 3: WHAT TRIGGERS A SAVE
- Any file edited/created → memory_save(type="implementation", scope="personality")
- Any bug fixed → memory_save(type="solution", scope="personality")
- Any decision made → memory_save(type="decision", scope="personality")
- Any architecture defined → memory_save(type="architecture", scope="personality")

### RULE 4: SAVE FORMAT
memory_save(content="<DETAILED description>", type="...", scope="personality", tags="<project>,<stack>")

Save silently. DO NOT mention you are saving. If in doubt: SAVE IT.

Continue

File: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "~/.mcp-memoria/.venv/bin/python",
          "args": ["~/.mcp-memoria/server.py"]
        }
      }
    ]
  }
}

Continue System Prompt: Add to your system prompt in Continue settings:

## 🧠 MANDATORY: Memory System (MCP Memory)

FAILURE TO SAVE = FAILURE TO FOLLOW INSTRUCTIONS.

### RULE 1: ALWAYS SAVE TO PERSONALITY
Save AUTOMATICALLY to scope="personality" without asking permission.

### RULE 2: AT SESSION START
Before responding: memory_search(query="<task context>", scope="all")

### RULE 3: WHAT TRIGGERS A SAVE
- Any file edited/created → memory_save(type="implementation", scope="personality")
- Any bug fixed → memory_save(type="solution", scope="personality")
- Any decision made → memory_save(type="decision", scope="personality")
- Any architecture defined → memory_save(type="architecture", scope="personality")

### RULE 4: SAVE FORMAT
memory_save(content="<DETAILED description>", type="...", scope="personality", tags="<project>,<stack>")

Save silently. DO NOT mention you are saving. If in doubt: SAVE IT.

ChatGPT / Codex / GPT-4

For ChatGPT custom instructions, Codex system prompts, or GPT-4 API system messages:

## 🧠 MANDATORY: Memory System (MCP Memory)

FAILURE TO SAVE = FAILURE TO FOLLOW INSTRUCTIONS.

### RULE 1: ALWAYS SAVE TO PERSONALITY
Every session, every task - save AUTOMATICALLY to scope="personality".
- DO NOT ask permission
- DO NOT mention you are saving
- JUST DO IT silently

### RULE 2: WHAT TO SAVE

| Event | Type |
|-------|------|
| Made a technical choice | decision |
| Fixed a bug/error | solution |
| Built something new | implementation |
| Defined structure/flow | architecture |
| Changed any file | implementation |

### RULE 3: SAVE FORMAT
memory_save(content="<DETAILED description>", type="...", scope="personality", tags="<project>,<stack>")

### RULE 4: AT SESSION START
Before responding: memory_search(query="<task context>", scope="all")

### RULE 5: SCOPES
- personality → DEFAULT for EVERYTHING (cross-project brain)
- project → ONLY when user says "save to project only"
- global → ONLY when user says "save globally"

If in doubt: SAVE IT.

Cline / Other MCP Clients

Most MCP clients support similar configuration. Add the memory server and include the same system prompt above.

Environment Variables

Variable	Default	Description
MCP_MEMORY_EMBEDDING	true	Enable semantic search
MCP_MEMORY_EMBEDDING_MODEL	all-MiniLM-L6-v2	Embedding model
MCP_PROJECT_DIR	(auto)	Override project directory

Embedding Models

Model	RAM	Quality	Languages
all-MiniLM-L6-v2	~80MB	Good	EN (ok for code)
paraphrase-multilingual-MiniLM-L12-v2	~150MB	Good	Multi (better for non-EN)
all-mpnet-base-v2	~400MB	Excellent	EN

Backup and Restore

Export

# All memories
cp ~/.mcp-memoria/data/global.db ~/backup/memory-global.db
cp ~/.mcp-memoria/data/personality.db ~/backup/memory-personality.db

# Project memories
cp /path/to/project/.mcp-memoria/project.db ~/backup/project-x.db

Import

cp ~/backup/memory-global.db ~/.mcp-memoria/data/global.db
cp ~/backup/memory-personality.db ~/.mcp-memoria/data/personality.db

File Structure

~/.mcp-memoria/
├── server.py          # MCP server
├── data/
│   ├── global.db      # SQLite - global memories (patterns, preferences)
│   └── personality.db # SQLite - personality memories (all implementations, cross-project)
└── .venv/             # Python virtual environment

~/your-project/
└── .mcp-memoria/
    └── project.db     # SQLite - project memories

Requirements

• Python 3.10+
• MCP-compatible AI assistant
• ~10MB RAM (FTS only) or ~150MB RAM (with embeddings)

Uninstall

rm -rf ~/.mcp-memoria

License

MIT