memories-mcp
Connect AI agents to the memories.sh memory layer via MCP (Model Context Protocol).
The CLI is the primary interface for memories.sh — use memories generate to create native config files for each tool. The MCP server is a fallback for real-time access when static configs aren't enough. It's also the best choice for browser-based agents (v0, bolt.new, Lovable) where the CLI can't run.
Quick Start
# Local stdio transport (most reliable)
memories serve
# HTTP/SSE transport (for web clients like v0)
memories serve --sse --port 3030
# Cloud-hosted (no local install needed)
# Endpoint: https://memories.sh/api/mcp
# Header: Authorization: Bearer YOUR_KEY
Primary Tool: get_context
Always start with get_context — it returns active rules + relevant memories in one call:
get_context({ query: "authentication flow" })
→ ## Active Rules
→ - Always use TypeScript strict mode
→ ## Relevant to: "authentication flow"
→ 💡 DECISION (P) abc123: Chose JWT for stateless auth
Leave query empty to get just rules. Use limit to control memory count (default: 10).
For lifecycle-aware callers on local CLI MCP, pass compaction/session hints:
get_context({
query: "checkout timeout",
session_id: "sess_123",
budget_tokens: 6000,
turn_count: 6,
turn_budget: 24,
last_activity_at: "2026-02-26T23:00:00.000Z",
inactivity_threshold_minutes: 45
})
These hints let the server trigger write-ahead checkpointing before destructive compaction.
When relationship extraction is enabled server-side, get_context may also return conflicts[] for contradiction-linked memories. Treat these as clarification prompts before taking irreversible actions.
Tool Selection Guide
| Goal |
Tool |
When |
| Start a task |
get_context |
Beginning of any task — gets rules + relevant context |
| Save knowledge |
add_memory |
After learning something worth persisting |
| Resolve contradictory context |
get_context |
If conflicts[] is present, ask a disambiguating question and persist the answer |
| Find specific info |
search_memories |
Full-text search with prefix matching |
| Browse recent |
list_memories |
Explore what's stored, filter by type/tags |
| Get coding standards |
get_rules |
When you only need rules, not memories |
| Update a memory |
edit_memory |
Fix content, change type, update tags |
| Remove a memory |
forget_memory |
Soft-delete (recoverable) |
| Bulk remove memories |
bulk_forget_memories |
Filtered mass soft-delete by type, tags, age, pattern |
| Reclaim storage |
vacuum_memories |
Permanently purge all soft-deleted records |
| Start lifecycle session (local) |
start_session |
Begin explicit session tracking |
| Persist turn checkpoint (local) |
checkpoint_session |
Save meaningful event/checkpoint |
| End session (local) |
end_session |
Close or compact active session |
| Read/create session snapshot (local) |
snapshot_session |
Capture raw transcript snapshot |
| Run consolidation (local) |
consolidate_memories |
Merge duplicates and supersede stale truths |
| Add reminder (local) |
add_reminder |
Create cron-based reminder in local CLI DB |
| Run reminders (local) |
run_due_reminders |
Emit due reminders and advance schedule |
| Manage reminders (local) |
list_reminders, enable_reminder, disable_reminder, delete_reminder |
Inspect and control reminder lifecycle |
Memory Types
When using add_memory, pick the right type:
- rule — Coding standards, preferences, constraints (always returned by
get_context)
- decision — Architectural choices with rationale
- fact — Project-specific knowledge (API limits, env vars, etc.)
- note — General notes (default)
- skill — Reusable agent workflows (use with
category and metadata)
Scopes
- project (default) — Scoped to current git repo, detected automatically
- global — Applies everywhere, set
global: true in add_memory
- project override — Set
project_id: "github.com/org/repo" in add_memory (or start_memory_stream) to force project scope when the MCP process is running outside that repo
Do not send both global: true and project_id in the same call.
Streaming Memory Tools
For collecting content from SSE sources (v0 artifacts, streaming responses):
start_memory_stream({ type?, tags?, global?, project_id? }) → returns stream_idappend_memory_chunk({ stream_id, chunk }) (repeat for each piece)finalize_memory_stream({ stream_id }) → creates memory + triggers embeddingcancel_memory_stream({ stream_id }) → discard if aborted
Lifecycle Tools (Local CLI MCP)
These tools are currently available when running memories serve locally:
start_session({ title?, client?, user_id?, metadata?, global?, project_id? })checkpoint_session({ session_id, content, role?, kind?, token_count?, turn_index?, is_meaningful? })end_session({ session_id, status? })snapshot_session({ session_id, source_trigger?, slug?, transcript_md?, message_count?, meaningful_only? })consolidate_memories({ types?, include_global?, global_only?, project_id?, dry_run?, model? })
MCP Resources
For clients that support MCP resources:
| URI |
Content |
memories://rules |
All active rules as markdown |
memories://recent |
20 most recent memories |
memories://project/{id} |
Memories for a specific project |
Transport Options
| Transport |
Use Case |
Command |
| stdio |
Claude Code, Cursor, local tools |
memories serve |
| HTTP/SSE |
v0, web-based agents, remote |
memories serve --sse --port 3030 |
| Cloud |
No local install, cross-device |
https://memories.sh/api/mcp + Authorization: Bearer KEY |
Local-only tools: lifecycle + reminders + streaming. Hosted MCP focuses on tenant-routed core memory tools.
Reference Files
- Client setup configs: See references/setup.md for copy-paste configs for every supported client
- Full tool reference: See references/tools.md for all parameters, return formats, and examples
1---2name: memories-mcp3description: MCP server integration for memories.sh — the persistent memory layer for AI agents. Use when: (1) Configuring the memories.sh MCP server for any client (Claude Code, Cursor, Windsurf, VS Code, v0, Claude Desktop, OpenCode, Factory), (2) Using MCP tools to store, search, retrieve memories, run lifecycle session workflows, or manage reminders, (3) Understanding get_context vs search_memories vs list_memories, (4) Working with streaming memory tools for SSE content, (5) Troubleshooting MCP connection issues, (6) Choosing between cloud MCP (HTTP) and local MCP (stdio) transports.4---56# memories-mcp78Connect AI agents to the memories.sh memory layer via MCP (Model Context Protocol).910> **The CLI is the primary interface for memories.sh** — use `memories generate` to create native config files for each tool. The MCP server is a **fallback** for real-time access when static configs aren't enough. It's also the **best choice for browser-based agents** (v0, bolt.new, Lovable) where the CLI can't run.1112## Quick Start1314```bash15# Local stdio transport (most reliable)16memories serve1718# HTTP/SSE transport (for web clients like v0)19memories serve --sse --port 30302021# Cloud-hosted (no local install needed)22# Endpoint: https://memories.sh/api/mcp23# Header: Authorization: Bearer YOUR_KEY24```2526## Primary Tool: `get_context`2728Always start with `get_context` — it returns active rules + relevant memories in one call:2930```31get_context({ query: "authentication flow" })32→ ## Active Rules33→ - Always use TypeScript strict mode34→ ## Relevant to: "authentication flow"35→ 💡 DECISION (P) abc123: Chose JWT for stateless auth36```3738Leave `query` empty to get just rules. Use `limit` to control memory count (default: 10).3940For lifecycle-aware callers on local CLI MCP, pass compaction/session hints:4142```43get_context({44 query: "checkout timeout",45 session_id: "sess_123",46 budget_tokens: 6000,47 turn_count: 6,48 turn_budget: 24,49 last_activity_at: "2026-02-26T23:00:00.000Z",50 inactivity_threshold_minutes: 4551})52```5354These hints let the server trigger write-ahead checkpointing before destructive compaction.5556When relationship extraction is enabled server-side, `get_context` may also return `conflicts[]` for contradiction-linked memories. Treat these as clarification prompts before taking irreversible actions.5758## Tool Selection Guide5960| Goal | Tool | When |61|------|------|------|62| Start a task | `get_context` | Beginning of any task — gets rules + relevant context |63| Save knowledge | `add_memory` | After learning something worth persisting |64| Resolve contradictory context | `get_context` | If `conflicts[]` is present, ask a disambiguating question and persist the answer |65| Find specific info | `search_memories` | Full-text search with prefix matching |66| Browse recent | `list_memories` | Explore what's stored, filter by type/tags |67| Get coding standards | `get_rules` | When you only need rules, not memories |68| Update a memory | `edit_memory` | Fix content, change type, update tags |69| Remove a memory | `forget_memory` | Soft-delete (recoverable) |70| Bulk remove memories | `bulk_forget_memories` | Filtered mass soft-delete by type, tags, age, pattern |71| Reclaim storage | `vacuum_memories` | Permanently purge all soft-deleted records |72| Start lifecycle session (local) | `start_session` | Begin explicit session tracking |73| Persist turn checkpoint (local) | `checkpoint_session` | Save meaningful event/checkpoint |74| End session (local) | `end_session` | Close or compact active session |75| Read/create session snapshot (local) | `snapshot_session` | Capture raw transcript snapshot |76| Run consolidation (local) | `consolidate_memories` | Merge duplicates and supersede stale truths |77| Add reminder (local) | `add_reminder` | Create cron-based reminder in local CLI DB |78| Run reminders (local) | `run_due_reminders` | Emit due reminders and advance schedule |79| Manage reminders (local) | `list_reminders`, `enable_reminder`, `disable_reminder`, `delete_reminder` | Inspect and control reminder lifecycle |8081## Memory Types8283When using `add_memory`, pick the right type:84- **rule** — Coding standards, preferences, constraints (always returned by `get_context`)85- **decision** — Architectural choices with rationale86- **fact** — Project-specific knowledge (API limits, env vars, etc.)87- **note** — General notes (default)88- **skill** — Reusable agent workflows (use with `category` and `metadata`)8990## Scopes9192- **project** (default) — Scoped to current git repo, detected automatically93- **global** — Applies everywhere, set `global: true` in `add_memory`94- **project override** — Set `project_id: "github.com/org/repo"` in `add_memory` (or `start_memory_stream`) to force project scope when the MCP process is running outside that repo9596Do not send both `global: true` and `project_id` in the same call.9798## Streaming Memory Tools99100For collecting content from SSE sources (v0 artifacts, streaming responses):1011021. `start_memory_stream({ type?, tags?, global?, project_id? })` → returns `stream_id`1032. `append_memory_chunk({ stream_id, chunk })` (repeat for each piece)1043. `finalize_memory_stream({ stream_id })` → creates memory + triggers embedding1054. `cancel_memory_stream({ stream_id })` → discard if aborted106107## Lifecycle Tools (Local CLI MCP)108109These tools are currently available when running `memories serve` locally:1101111. `start_session({ title?, client?, user_id?, metadata?, global?, project_id? })`1122. `checkpoint_session({ session_id, content, role?, kind?, token_count?, turn_index?, is_meaningful? })`1133. `end_session({ session_id, status? })`1144. `snapshot_session({ session_id, source_trigger?, slug?, transcript_md?, message_count?, meaningful_only? })`1155. `consolidate_memories({ types?, include_global?, global_only?, project_id?, dry_run?, model? })`116117## MCP Resources118119For clients that support MCP resources:120121| URI | Content |122|-----|---------|123| `memories://rules` | All active rules as markdown |124| `memories://recent` | 20 most recent memories |125| `memories://project/{id}` | Memories for a specific project |126127## Transport Options128129| Transport | Use Case | Command |130|-----------|----------|---------|131| **stdio** | Claude Code, Cursor, local tools | `memories serve` |132| **HTTP/SSE** | v0, web-based agents, remote | `memories serve --sse --port 3030` |133| **Cloud** | No local install, cross-device | `https://memories.sh/api/mcp` + `Authorization: Bearer KEY` |134135Local-only tools: lifecycle + reminders + streaming. Hosted MCP focuses on tenant-routed core memory tools.136137## Reference Files138139- **Client setup configs**: See [references/setup.md](references/setup.md) for copy-paste configs for every supported client140- **Full tool reference**: See [references/tools.md](references/tools.md) for all parameters, return formats, and examples
webrenew