Skip to main content
Glama

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

Other MCP clients

npx -y memoir-mcp

Related 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

log_attempt

Record something that was tried and its outcome.

log_blocker

Flag something that's stuck and why.

resolve_blocker

Mark a blocker as resolved with what fixed it.

log_decision

Record a design or architecture choice and its rationale.

end_session

Close the current session with an optional summary.

Read

Tool

Description

get_handoff

Structured summary of the last session -- what was attempted, what's blocked, what was decided.

get_history

Query past sessions (default: last 3, max 20).

get_blockers

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

MEMOIR_MAX_CONTENT

500

Max characters for content fields

MEMOIR_MAX_OUTCOME

300

Max characters for outcome/resolution fields

MEMOIR_MAX_ENTRIES

50

Max entries per session

MEMOIR_MAX_SESSIONS

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

Handoff output uses a compact format to keep context window usage low.

License

MIT

Available Tools

8 tools
end_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

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: session management, blocker tracking, history queries, and logging attempts/decisions/resolutions. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: 'end_', 'get_', 'log_', 'resolve_'. Underscore separation is used throughout, ensuring predictability.

    Tool Count5/5

    8 tools is well-scoped for a session and blocker management server, covering all core operations without being overwhelming or sparse.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers