Automatic project resolution
Resolve or create projects from repo context automatically, without asking users for a project id every time.
Memory MCP Server
Long-term project memory for AI models and coding agents
Memory MCP stores architecture, decisions, tasks, warnings, preferences, and session state so your AI tools can resume work exactly where they left off.
Interactive index
Jump directly to the area you need and keep implementation steps easy to follow.
Why teams use it
Built for teams that want MCP project memory, Supabase persistent context, AI agent memory, and reliable handoff between OpenCode, Claude Code CLI, Qwen Code, Codex, and native sessions.
Git-aware memory
Capture repo path, remote, branch, commit, and working tree status so memory stays aligned with real code changes.
Session summaries and checkpoints
Store what was done, what is left, blockers, and the next step whenever a session ends or changes client.
File-level memory
Document key files, modules, and dependencies so future sessions know how parts of the project relate.
Semantic search
Search saved memory by meaning with embeddings in Supabase, while keeping a lexical fallback for portability.
Retention and exports
Keep storage efficient with retention policies, timeline summaries, and JSON or Markdown exports for backup or transfer.
Setup in five steps
Minimal setup, keyboard-friendly navigation, and responsive guidance for desktop, tablet, and mobile.
- 1
Clone the repository and install Python dependencies.
- 2
Create a Supabase project and run the provided schema.sql file.
- 3
Copy .env.example to .env and add your public values.
- 4
Register the server in mcp.json or your MCP-compatible client settings.
- 5
Start the server and verify shared memory across interfaces.
Use it with natural language
In most MCP-compatible clients, you talk to the model normally and it decides which tool to call when tool use is enabled.
Talk normally
You do not need to manually name a tool for common tasks. Ask for the context, ask what changed, or ask to continue the project.
The model selects tools
If the client exposes Memory MCP tools, the model can call `load_unified_context`, `capture_project_memory`, `sync_session_state`, or other tools automatically based on your request.
Force a tool only when needed
Manual tool calls are useful for debugging, integrations, or when you want exact control over inputs and outputs.
Projects are detected automatically
When the client exposes the active repo or workspace, Memory MCP can resolve or create the right project automatically, even if you open a new repo in the IDE.
Prompt examples
Resume this project and tell me where we left off.
Load the stored project memory before continuing the refactor.
Save this architecture decision and mark the current task as in progress.
Save everything important from this session in Memory MCP.
If this is a new project, create what you need in Memory MCP and start saving memory automatically.
If a client disables tool use, the model cannot call MCP tools automatically. In that case, enable MCP tools in the client or call the tool explicitly.
Configuration
You can keep this repository in the folder you prefer. Most users clone it once, keep a private `.env`, and connect multiple IDEs or AI clients to the same MCP server.
1. Clone and prepare the server
Clone the repository, install dependencies, run `pip install -e .`, create `.env`, run `schema.sql` in Supabase, and keep the folder in a stable location.
git clone https://github.com/dannymaaz/memory-mcp.git
cd memory-mcp
python -m venv .venv
pip install -r requirements.txt
pip install -e .
Required .env values
The MCP server only needs three values for normal use: SUPABASE_URL, SUPABASE_KEY, and OWNER_ID. DATABASE_URL is optional and only matters if you also want direct Postgres access for admin tasks or SQL tooling.
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
OWNER_ID=your-stable-identifier
DATABASE_URL=postgresql://user:password@host:6543/postgres
How to get each value
SUPABASE_URL and SUPABASE_KEY come from your Supabase project settings. OWNER_ID is not provided by Supabase: you choose a stable identifier such as your GitHub username, company slug, or workspace id and keep using the same value.
macOS and Linux
The MCP is not Windows-only. After `pip install -e .`, macOS and Linux expose the same `memory-mcp` command, so the same MCP server entry works across platforms.
python3 -m venv .venv
source .venv/bin/activate
cp .env.example .env
2. Keep one central installation
Do not copy the server into every project. Keep one stable folder for the MCP server and connect all clients to that same installation.
cp .env.example .env
memory-mcp
3. Use one standard MCP command
After installation, configure clients to launch the same command: memory-mcp. This makes the server behave like any other stdio MCP server.
"command": "memory-mcp"
"env": { "SUPABASE_URL": "..." }
4. Do I need to start it after every reboot?
Usually no. When a client is configured with the `memory-mcp` command, it normally starts the server automatically when needed. You only need to run it manually when testing it directly or debugging outside the client.
Works with other MCP clients
If an IDE or agent accepts a standard MCP JSON config with an mcpServers entry, you can usually paste the same server block and only adjust environment values.
mcpServers.memory-mcp
OpenCode
Point OpenCode to the shared MCP config or paste the same server block into its settings. PROJECT_MEMORY_INTERFACE is optional if you want to force a client label; most setups can skip it.
opencode --mcp-config mcp.json
Codex
Register the same server block in Codex MCP settings, then launch Codex with that configuration.
codex --config mcp.json
Claude Desktop
Add a local MCP server entry to Claude Desktop using the installed memory-mcp command and the same environment variables from your local setup.
Claude Desktop path by platform
%APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: check your local Claude Desktop app data folder
"command": "memory-mcp"
Claude Code CLI
Run Claude Code with the shared MCP config or the equivalent CLI registration flow.
claude-code --mcp-config mcp.json
Antigravity
Paste the same MCP JSON into Antigravity MCP settings. On Windows, a common config location is shown below.
%USERPROFILE%\.gemini\antigravity\mcp_config.json
"command": "memory-mcp"
Qwen Code
Point Qwen Code to the same MCP config or paste the shared server block into its settings. PROJECT_MEMORY_INTERFACE is optional if you want to force a client label.
qwen --mcp-config mcp.json
Generic MCP config snippet
{
"mcpServers": {
"memory-mcp": {
"command": "memory-mcp",
"env": {
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_KEY": "your-anon-key",
"OWNER_ID": "your-stable-identifier"
}
}
}
}Common Antigravity path on Windows
%USERPROFILE%\.gemini\antigravity\mcp_config.json
Core MCP tools
The API focuses on loading shared context, saving decisions, syncing session state, and measuring interface usage.
resolve_project
Resolve or create the current project automatically from repository context.
load_unified_context
Load durable project memory optimized for the current interface and model.
save_cross_interface_decision
Persist a decision so future sessions inherit the same reasoning.
save_file_memory
Store file summaries, dependencies, and module relationships for later sessions.
save_checkpoint
Save architecture checkpoints, blockers, functional state, and next steps.
sync_session_state
Store the current working state so another AI client can continue the same task.
capture_project_memory
Store decisions, tasks, checkpoints, file memory, prompts, and session state in one call.
search_semantic_memory
Search memory documents by embedding similarity or lexical fallback.
resume_project
Return a resume-ready view with progress, warnings, and recommended next action.
get_interface_analytics
Measure usage patterns across OpenCode, Claude Code CLI, Qwen Code, Codex, and native workflows.
FAQ
Quick answers for the most common setup and usage questions.
What is OWNER_ID?
OWNER_ID is a stable identifier that you choose yourself. It is not created by Supabase. Good options include your GitHub username, a team slug, or a workspace id.
Do I need DATABASE_URL?
No for normal use. SUPABASE_URL and SUPABASE_KEY are enough for the MCP server. DATABASE_URL is only useful for direct Postgres access, admin scripts, or manual SQL tooling.
Do I need project_id every time?
No. Memory MCP tries to resolve the active project automatically from repository context and can create it when missing.
Can I just tell it to save everything?
Yes. If the client exposes tool use, the model can call capture_project_memory to save decisions, tasks, warnings, checkpoints, file memory, prompts, and session state in one step.
Do I need to start it after every reboot?
Usually no. MCP-compatible clients normally spawn memory-mcp on demand once they are configured with the command.
Prompt recipes by client
Use these prompt patterns when you want the model to save, resume, or structure memory with the right level of detail.
Antigravity
Useful when you want long-running planning sessions to save everything important without naming each tool manually.
Use Memory MCP for this project. If you detect important decisions, blockers, tasks, or next steps, save them automatically while we work.
Before we finish, save everything important from this session in Memory MCP and leave me the next recommended step.
OpenCode
Useful for code-heavy work where file memory, dependencies, and checkpoints matter.
Use Memory MCP while we refactor. Document important files, dependencies, architectural decisions, and task progress automatically.
If this repository is new to Memory MCP, create the project automatically and start storing context as we go.
Claude Code CLI
Useful when you want a concise working summary and strong handoff between sessions.
Retoma este proyecto con Memory MCP y dame un resumen de lo hecho, lo que falta y el siguiente paso recomendado.
When we stop, capture the full session in Memory MCP, including decisions, tasks, warnings, prompts, and a checkpoint summary.
Codex
Useful when you want delegated coding work to keep the same warnings, tasks, and file memory context.
Use Memory MCP while implementing this task. Keep warnings, task status, and important file memory synchronized as you code.
Before handing control back, save everything important from this coding session in Memory MCP and tell me the next safe step.
Qwen Code
Useful for code generation and refactors where you want memory to stay aligned with module relationships and checkpoints.
Use Memory MCP during this refactor. Save architectural decisions, file relationships, and task progress automatically.
If this repository is new, create the project in Memory MCP and start capturing context as we modify the codebase.
Examples by interface
Switch views to compare OpenCode, Claude Code CLI, and Codex workflows using the same project memory backend.
OpenCode workflow
Load project memory before editing so OpenCode inherits architecture, previous decisions, and active warnings.
Launch OpenCode with the MCP config
opencode --mcp-config mcp.json
Claude Code CLI workflow
Use the same stored memory to resume implementation, debugging, or planning from the last recorded session state.
Launch Claude Code CLI with the MCP config
claude-code --mcp-config mcp.json
Codex workflow
Preserve warnings, tasks, and synced session state when handing off coding work to Codex.
Launch Codex with the MCP config
codex --config mcp.json