memoir-mcp
memoir-mcp provides persistent memory for AI agents across sessions by logging attempts, blockers, decisions, and handoffs to a local SQLite database — no external services or API keys required.
Write Tools:
log_attempt— Record something that was tried along with its outcomelog_blocker— Flag an obstacle and document why it's blockedresolve_blocker— Mark a blocker as resolved by providing its ID and what fixed itlog_decision— Record a design or architectural decision and its rationaleend_session— Explicitly close the current session with an optional summary
Read Tools:
get_handoff— Retrieve a structured summary of the last session (attempts, blockers, decisions) to quickly get up to speedget_history— Query past sessions for the current project (default: last 3, up to 20)get_blockers— List unresolved or resolved blockers across all sessions for the project
Key behaviors:
Auto-detects projects via git root and implicitly creates sessions
Stores all data locally in
~/.memoir/memoir.dbRetains up to 20 sessions per project, automatically pruning older ones
Configurable via environment variables (
MEMOIR_MAX_CONTENT,MEMOIR_MAX_OUTCOME,MEMOIR_MAX_ENTRIES,MEMOIR_MAX_SESSIONS)Compatible with any MCP client (Claude Code, Cursor, Codex, Windsurf, etc.)
Uses Git repository roots to provide automatic project detection, ensuring that session journals and persistent memory logs are correctly scoped to the current project.
memoir-mcp
Structured session journals for AI agents. Persistent memory across sessions -- no more repeating dead ends.
When a session ends, all reasoning is lost -- what was tried, what failed, what's blocked. The next session starts from scratch and repeats the same mistakes. memoir logs it all and hands it off so the next session picks up where the last one left off.
Works with any MCP client: Claude Code, Cursor, Codex, Windsurf, and more.
Install
Claude Code
claude mcp add memoir -s user -- npx -y memoir-mcpOther MCP clients
npx -y memoir-mcpRelated MCP server: MCP Session Memory Bridge
How it works
Automatic project detection -- identifies the project by its git root, so logs stay scoped without any configuration.
Implicit sessions -- a session is created automatically on first log. No setup step.
Rolling retention -- keeps the last 20 sessions per project (configurable). Old sessions are pruned automatically.
Tools
Write
Tool | Description |
| Record something that was tried and its outcome. |
| Flag something that's stuck and why. |
| Mark a blocker as resolved with what fixed it. |
| Record a design or architecture choice and its rationale. |
| Close the current session with an optional summary. |
Read
Tool | Description |
| Structured summary of the last session -- what was attempted, what's blocked, what was decided. |
| Query past sessions (default: last 3, max 20). |
| List unresolved (or resolved) blockers across all sessions. |
Storage
Single SQLite file at ~/.memoir/memoir.db. No API keys, no external services.
Configuration
All limits are configurable via environment variables:
Variable | Default | Description |
| 500 | Max characters for content fields |
| 300 | Max characters for outcome/resolution fields |
| 50 | Max entries per session |
| 20 | Max sessions per project (rolling) |
Example with custom limits:
claude mcp add memoir -s user -e MEMOIR_MAX_CONTENT=1000 -e MEMOIR_MAX_ENTRIES=100 -- npx -y memoir-mcpHandoff output uses a compact format to keep context window usage low.
License
MIT
Available Tools
8 toolsend_sessionEnd SessionB
Explicitly close the current session with an optional summary.
Inputs: summary.
get_blockersGet BlockersA
List blockers across all sessions for this project.
Inputs: resolved.
get_handoffGet HandoffA
Get a structured summary of the last session for this project. Use this at the start of a new session to understand what was previously attempted, what's blocked, and what decisions were made.
Inputs: no named parameters.
get_historyGet HistoryB
Query past sessions for this project.
Inputs: sessions_back.
log_attemptLog AttemptC
Record something that was tried and its outcome.
Inputs: content (required), outcome.
log_blockerLog BlockerC
Flag something that's stuck and why.
Inputs: content (required).
log_decisionLog DecisionB
Record a design or architecture choice and its rationale.
Inputs: content (required).
resolve_blockerResolve BlockerB
Mark a blocker as resolved.
Inputs: blocker_id (required), resolution (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool serves a distinct purpose: session management, blocker tracking, history queries, and logging attempts/decisions/resolutions. No two tools overlap in functionality.
All tool names follow a consistent verb_noun pattern: 'end_', 'get_', 'log_', 'resolve_'. Underscore separation is used throughout, ensuring predictability.
8 tools is well-scoped for a session and blocker management server, covering all core operations without being overwhelming or sparse.
The tool set covers most key operations (close session, list/resolve blockers, log decisions/attempts, query history), but lacks an explicit 'start session' tool, which is a minor gap.
Maintenance
Related MCP Connectors
Persistent memory for AI agents: save, search and connect context across tools and sessions.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory for AI agents. Search, store, and recall across sessions.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Related MCP Servers
- AlicenseAqualityBmaintenanceGive your AI the ability to read the web. Fetches URLs as clean markdown with 9 fallback strategies.5230 npm9MIT
- FlicenseNot gradedqualityNot gradedmaintenanceProvides cross-session memory for AI agents by maintaining a rolling 24-hour event stream and searchable daily archives to prevent context loss. It enables agents to record, query, and retrieve historical events and decisions through a structured markdown-based workspace.1 npm-
- AlicenseNot gradedqualityBmaintenanceProvides persistent memory for AI coding agents across sessions by saving and loading session context like tasks, decisions, and blockers.612 npmMIT
- AlicenseNot gradedqualityDmaintenancePersistent activity journal for AI agents - enables logging and querying decisions, changes, errors, and observations across sessions.3 npm1MIT