Pensieve

A persistent memory MCP server for Claude Code that remembers decisions, preferences, and context across conversation boundaries.

"I use the Pensieve. One simply siphons the excess thoughts from one's mind, pours them into the basin, and examines them at one's leisure." — Albus Dumbledore

Problem

When Claude Code conversations are compacted or cleared:

• Agent "forgets" discovered patterns, decisions, and understanding
• User re-explains the same context repeatedly
• Agent may hallucinate or contradict previous decisions
• Momentum lost every few hours of deep work

Solution

Pensieve provides persistent storage via SQLite that Claude can access through native tool calls:

• pensieve_remember — Save decisions, preferences, discoveries, entities
• pensieve_recall — Query the knowledge base
• pensieve_session_start — Load context at conversation start
• pensieve_session_end — Persist learnings before ending

Installation

Option 1: npx (Recommended)

claude mcp add pensieve npx @esparkman/pensieve

That's it! Restart Claude Code and the tools are available.

Option 2: Clone and Build

# Clone the repository
git clone https://github.com/esparkman/pensieve.git ~/Development/pensieve
cd ~/Development/pensieve

# Install dependencies and build
npm install
npm run build

# Add to Claude Code
claude mcp add pensieve node ~/Development/pensieve/dist/index.js

Option 3: Docker

# Clone the repository
git clone https://github.com/esparkman/pensieve.git
cd pensieve

# Build the Docker image
docker build -t pensieve .

# Add to Claude Code (mount your project for local database)
claude mcp add pensieve docker run -i --rm \
  -v "$PWD/.pensieve:/app/.pensieve" \
  -v "$HOME/.claude-pensieve:/root/.claude-pensieve" \
  pensieve

Note: The Docker approach mounts two volumes:

• $PWD/.pensieve — Project-local database (if in a git repo)
• $HOME/.claude-pensieve — Global fallback database

Verify Installation

After installing, restart Claude Code and check that Pensieve is loaded:

# In a new Claude Code session, the tools should be available:
# pensieve_status, pensieve_remember, pensieve_recall, etc.

Usage

After installing, Claude Code will have access to these tools:

Start a session

At the beginning of each conversation, Claude should call:

pensieve_session_start()

This loads the last session's summary, work in progress, key decisions, and preferences.

Remember things

pensieve_remember({
  type: "decision",
  topic: "authentication",
  decision: "Use Devise with magic links",
  rationale: "Passwordless is more secure and user-friendly"
})

pensieve_remember({
  type: "preference",
  category: "testing",
  key: "approach",
  value: "system tests for UI flows"
})

pensieve_remember({
  type: "entity",
  name: "Customer",
  description: "End user who places orders",
  relationships: '{"belongs_to": ["Tenant"], "has_many": ["Orders"]}'
})

pensieve_remember({
  type: "discovery",
  category: "component",
  name: "ButtonComponent",
  location: "app/components/base/button_component.rb",
  description: "Primary button component with variants"
})

Recall things

pensieve_recall({ query: "authentication" })
pensieve_recall({ type: "preferences" })
pensieve_recall({ type: "entities" })
pensieve_recall({ type: "session" })
pensieve_recall({ type: "questions" })

End a session

Before ending a conversation:

pensieve_session_end({
  summary: "Completed invoice list component with filtering",
  work_in_progress: "Invoice detail view partially designed",
  next_steps: "Complete detail view, add PDF export",
  key_files: ["app/components/invoices/invoice_list_component.rb"],
  tags: ["invoices", "ui"]
})

Database Location

Pensieve stores data in SQLite:

• Project-local (if .git or .pensieve exists): .pensieve/memory.sqlite
• Global (fallback): ~/.claude-pensieve/memory.sqlite

This means each project gets its own memory, but you also have a global memory for general preferences.

Environment Variable Override

Set PENSIEVE_DB_PATH to explicitly specify the database location:

PENSIEVE_DB_PATH=/custom/path/memory.sqlite claude mcp add pensieve ...

Security

Secrets Detection

Pensieve automatically detects and refuses to store potential secrets including:

• API keys (AWS, GitHub, Stripe, etc.)
• Database connection strings with passwords
• Bearer tokens and private keys
• Credit card numbers and SSNs

If a secret is detected, the data is NOT saved and a warning is displayed.

Storage Limits

To prevent unbounded growth:

• Decisions: Max 1,000 (oldest auto-pruned)
• Discoveries: Max 500 (oldest auto-pruned)
• Sessions: Older than 90 days auto-deleted
• Field length: Max 10KB per field (truncated with warning)

Data Storage

Data is stored in plaintext SQLite. Do NOT store:

• Passwords or API keys
• Personal identifying information
• Financial credentials
• Any sensitive secrets

The database is local-only and never transmitted over the network.

Tools Reference

| Tool | Purpose | |------|---------| | pensieve_remember | Save decisions, preferences, discoveries, entities, or questions | | pensieve_recall | Query the knowledge base | | pensieve_session_start | Start a session and load prior context | | pensieve_session_end | End a session and save a summary | | pensieve_resolve_question | Mark an open question as resolved | | pensieve_status | Get database location and counts |

Data Types

Decisions

Important choices with rationale. Searchable by topic.

Preferences

User conventions (coding style, testing approach, naming patterns).

Discoveries

Things found in the codebase (components, patterns, helpers).

Entities

Domain model understanding (models, relationships, attributes).

Sessions

Summaries of work sessions for continuity.

Open Questions

Unresolved blockers or questions to address.

Hooks Integration

Pensieve includes a CLI that integrates with Claude Code's hooks system for automatic context preservation.

Quick Setup

Copy the example hooks configuration:

cp node_modules/@esparkman/pensieve/hooks/settings.json ~/.claude/settings.json

Or add to your existing settings:

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
      },
      {
        "matcher": "manual",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
      },
      {
        "matcher": "resume",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
      }
    ]
  }
}

CLI Commands

| Command | Purpose | |---------|---------| | pensieve auto-save | Save session snapshot (for PreCompact hooks) | | pensieve load-context | Output last session context to stdout | | pensieve status | Show database location and counts |

CLI Options

# Auto-save with custom summary
pensieve auto-save --summary "Completed auth feature" --wip "Testing in progress"

# Load context as JSON
pensieve load-context --format json

See hooks/README.md for detailed configuration options.

Development

cd ~/Development/pensieve
npm install
npm run dev    # Run with tsx for development
npm run build  # Build TypeScript

License

MIT