# Memories MCP

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

- Skill: `webrenew/memories-mcp` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add webrenew/memories-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/memories-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/memories-mcp

---


# 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

```bash
# 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):

1. `start_memory_stream({ type?, tags?, global?, project_id? })` → returns `stream_id`
2. `append_memory_chunk({ stream_id, chunk })` (repeat for each piece)
3. `finalize_memory_stream({ stream_id })` → creates memory + triggers embedding
4. `cancel_memory_stream({ stream_id })` → discard if aborted

## Lifecycle Tools (Local CLI MCP)

These tools are currently available when running `memories serve` locally:

1. `start_session({ title?, client?, user_id?, metadata?, global?, project_id? })`
2. `checkpoint_session({ session_id, content, role?, kind?, token_count?, turn_index?, is_meaningful? })`
3. `end_session({ session_id, status? })`
4. `snapshot_session({ session_id, source_trigger?, slug?, transcript_md?, message_count?, meaningful_only? })`
5. `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](references/setup.md) for copy-paste configs for every supported client
- **Full tool reference**: See [references/tools.md](references/tools.md) for all parameters, return formats, and examples