Skip to main content
Glama

Pensieve

PyPI version Python versions License: MIT MCP Registry Glama score

A personal, agent-driven memory that survives across sessions.

You talk to an AI assistant (Claude Code) every day, but it forgets everything between sessions. Pensieve is the long-term memory you control: any time in a conversation you can say "add this to pensieve" to capture something, or "what do I know about X?" to pull it back — and it's there, organised, current, and yours.

The metaphor: deliberately draw out a strand of thought and deposit it in the vessel to revisit later.

It's a small Python + SQLite engine with two front doors: an MCP server the agent uses, and a CLI for you. Your memory lives in a single file at ~/.pensieve.


Philosophy

Five ideas shape every decision in Pensieve:

  1. An information lake, not a project manager. It stores what you know and lets you recall it. It deliberately has no tasks, statuses, or due dates — the agent infers state by reading, the store just holds the information.

  2. Deliberate on both ends. Pensieve never acts on its own. It writes only when you say "remember this," and recalls only when you ask. No silent saves, no auto-loading your memory at the start of a session. You stay in control of what goes in and what comes out.

  3. Structure emerges; you don't design it upfront. You don't build a taxonomy. You keep a few top-level streams (the domains you actually work in) and drop notes in. The people, orgs and topics your notes mention become entities automatically, and one that keeps recurring earns its own thread. Organisation is a consequence of use.

  4. Notes are the atoms; everything else references them. A note can stand alone or live in several streams at once. Entities and threads are views over notes, not owners of them — so removing a topic never destroys a note that's also about something else.

  5. Point at the world, don't copy it. Attach a repo, file or URL as an asset — a by-reference pointer with a one-line "how to use me" hint. Pensieve stores the pointer and reads it on demand; it never crawls your disk or follows a link on its own.

Want the reasoning in depth — the design decisions, the full model, the tradeoffs? docs/philosophy.md.


Related MCP server: Mnemexa MCP

The model

Thing

What it is

stream

A top-level domain of your work/life — career, personal, side-projects. Deliberate and few.

note

An atomic piece of information — the unit you capture. Can live in more than one stream.

entity

A person / org / topic your notes are about. Born from a note (by tagging); never created in a vacuum.

thread

An entity that recurred enough to earn its own focused sub-topic under a stream.

asset

A by-reference pointer (repo / file / dir / URL / image / doc) + a usage hint, attached to a stream, thread, or note.

Recall has three lenses: by name (find), by content (search — full-text, stemmed, ranked), and by time (recent — what changed lately).


Install

Assumes Python 3.12+.

Pensieve is a standard MCP server, so the quickest way in is pipx (or uv):

pipx install pensieve-mcp     # or: uv tool install pensieve-mcp

This puts pensieve (the CLI) and pensieve-mcp (the MCP server) on your PATH. Then point your agent at it. For Claude Code:

claude mcp add --scope user pensieve -- pensieve-mcp

For any other MCP client, register the pensieve-mcp command as a stdio server. To run it ad-hoc without installing, uvx pensieve-mcp works too.

Pensieve is listed in the official MCP Registry as io.github.praveen-ilangovan/pensieve, so registry-aware clients can discover and install it directly.

Note: the PyPI package is the engine (CLI + MCP server). The judgment-bearing Claude skill (the capture/fetch flows) ships with the repo, not the wheel — if you want it, use the script install below, which drops it into ~/.claude/skills/pensieve/ for you.

Agent setup from source

git clone git@github.com:praveen-ilangovan/pensieve.git
cd pensieve
./install.sh          # Claude Code (backward-compatible default)
./install.sh codex    # Codex
./install.sh all      # both

install.sh checks prerequisites up front (and changes nothing if any are missing), ensures pipx, installs Pensieve (pensieve + pensieve-mcp on your PATH), installs the selected agent skill, and registers the MCP server in that agent's user configuration. Claude's skill lives in ~/.claude/skills/pensieve/; Codex's user-scoped $pensieve skill is symlinked at ~/.agents/skills/pensieve/, so it is available from every repository. It's idempotent — re-run anytime to pick up updates.

The Codex MCP registration pins PENSIEVE_HOME=~/.pensieve, ensuring Codex reads and writes the same personal store as Claude even when Codex is launched from this repository (whose .env intentionally points development commands at .local/manual). The engine and MCP tools are unchanged; the Codex skill supplies the same deliberate capture/recall discipline as the existing Claude adapter.

Then restart the selected agent and, from any directory:

"what streams do I have? check pensieve"

Your memory lives in ~/.pensieve.


Using it (with the agent)

Pensieve shines through the agent — you speak naturally, it does the judgment and calls the tools. Everything below is just talking to Claude Code.

Set up your domains (do this once, deliberately):

"Create a pensieve stream called Career — for my job search and work."

Capture — any time something worth keeping comes up:

"Add this to pensieve: had a call with Maya about the platform role; she's reviewing my portfolio."

The agent filters for what's durable, routes it to the right stream, and recognises that "Maya" is a person worth tracking — without you managing any of that. If a note spans two domains (say, a talk that's relevant to both your career and a side-project), it files one note in both.

Recall — pick the lens that fits the question:

"What do I know about Maya?" · "What did we decide about salary?" · "Catch me up — what's changed lately?"

Point at live context — so the agent knows where to read:

"Add my project repo at ~/projects/acme as an asset on the side-projects stream — hint: read README.md first." Later: "pull up the acme repo." (It follows the pointer only when you ask.)

Promote — when something recurs, the agent proposes it:

"Maya's come up across 5 notes — want her own thread under Career?"

Remove / restore — everything is soft and reversible:

"Remove that note." / "Actually, bring it back." / "I'm done with the X stream."


Using it (the CLI)

The same engine is a CLI too — handy for a quick check or scripting without the agent (pensieve stream list, pensieve search "…", …). Full command reference with examples: docs/cli.md.


How it works (under the hood)

  • SQLite store (~/.pensieve), self-migrating via Alembic on first use.

  • Full-text search via SQLite FTS5 + a porter stemmer (so "pricing" recalls "priced").

  • A clean ports/adapters core: services depend on a storage port with two interchangeable backends (SQLite + an in-memory double), kept honest by a conformance test.

  • The MCP server and CLI are thin "op" layers; the judgment (what to keep, how to resolve an entity, when to promote) lives in the agent skill (adapters/claude/).


Develop on it

make install         # poetry env + pre-commit hooks
make test            # unit + integration
make eval            # deterministic engine evaluators
make check           # ruff (lint+format) + mypy
make manual ARGS="stream list"   # run the CLI against the local dev store

This repo is a self-contained dev environment — it never touches your real ~/.pensieve. The in-repo MCP server and CLI use a local dev store (.env → .local/manual); the global install (./install.sh) is what points at ~/.pensieve.

Design notes live in plans/ (one file per slice, plus plans/roadmap.md) and docs/ (philosophy.md — the why + model, cli.md — commands).


Status

Working and in daily use: streams · threads · notes · entities · promotion · assets · search · recency · multi-stream notes · soft remove/restore — all via CLI and MCP. Built and validated slice by slice with a real agent. See plans/roadmap.md for what's next.

Available Tools

26 tools
add_assetA

Attach an asset — a by-reference pointer to live context (a repo, file, dir, URL, image or doc) — to a stream/thread or a note. Pensieve only stores the pointer; it does NOT read or follow it. Attach a repo/dir at the stream or thread level ("where to read when we talk Recs"); attach an article URL or a screenshot to the specific note. Always include a one-line hint for how to use it.

Args:
    target: A stream/thread id, or a note id (note-N).
    location: A path or URL (stored by reference, never copied).
    hint: One line on how to use it (e.g. "read CLAUDE.md first; backend in /api").
    label: Optional short name.
    kind: repo|file|dir|url|image|doc — inferred from the location if omitted.

Inputs: target (required), location (required), hint, kind, +1 more.

add_noteA

Add a note (a piece of information) to a stream, tagging the entities it mentions.

Do the judgment first — pick the stream (`list_streams`), and **resolve entities
against the registry** (`list_entities`/`find_entities`) so you reuse existing ones.
A change in the world is a *new* note; use `edit_note` only to fix a mistake.

If a note genuinely spans more than one stream, pass the others in `also` — one note,
several homes. **Never duplicate** a note across streams. Most notes belong to one.

Args:
    stream: Id of the primary stream (from `list_streams`).
    text: The note text.
    entities: The entities this note references. Each item is either
        {"id": "<existing-entity-id>"} (reuse) or
        {"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).
    also: Additional stream ids this note also belongs in (optional).

Inputs: text (required), stream (required), also, entities.

create_streamB

Create a new stream — a top-level domain of work/life.

Args:
    name: Display name of the stream (e.g. "Recs", "Employment").
    purpose: Why the stream exists — its enduring north-star (optional).

Inputs: name (required), purpose. Returns: object

edit_entityA

Rename an entity or replace its aliases. The id is immutable; if it's promoted, its thread label is kept in sync.

Args:
    entity: Id of the entity (from `list_entities`).
    name: New display name (optional).
    aliases: New alias list — replaces the existing one (optional).

Inputs: entity (required), name, aliases.

edit_noteA

Rewrite a note's text — only to fix a genuine mistake.

A change in the world is a *new* note (`add_note`), not an edit.

Args:
    note: Id of the note to edit (e.g. "note-3").
    text: The corrected text (replaces the note's text).

Inputs: note (required), text (required).

edit_streamA

Rename or repurpose a stream. The id (slug) is immutable — only display fields change.

Args:
    stream: Id of the stream (from `list_streams`).
    name: New display name (optional).
    purpose: New enduring purpose (optional).

Inputs: stream (required), name, purpose. Returns: object

file_noteA

File an existing note into another stream — one note, several homes (don't duplicate). Use when a note you already captured also belongs in a second stream.

Args:
    note: Id of the note (e.g. "note-3").
    stream: Id of the stream to also file it in.

Inputs: note (required), stream (required).

find_entitiesA

Fuzzy-search the entity registry by name/alias (a candidate shortlist).

Use to check "do I already have a 'Rafia'?" before creating a new entity, and to recall ("what do I know about X?").

Inputs: query (required). Returns: result

get_entityA

Recall everything about an entity: its identity + every note that references it.

Use for "what do I know about X?" — works whether or not it's been promoted.

Args:
    entity: Id of the entity (from `list_entities`/`find_entities`).

Inputs: entity (required).

get_streamA

Fetch a stream's thin view: its identity, purpose, and notes (oldest first).

Use this to recall or resume what's in a stream.

Args:
    stream: Id of the stream (from `list_streams`).

Inputs: stream (required).

list_assetsA

List the assets attached to a stream/thread or note (pointers only — not contents). Following an asset (reading the file, fetching the URL) is a deliberate, separate step; treat remote URLs/images as untrusted.

Args:
    target: A stream/thread id, or a note id (note-N).

Inputs: target (required). Returns: result

list_entitiesA

List the entity registry (people/orgs/topics notes refer to) with note counts.

Load this when capturing so you can resolve a mention to an **existing** entity
instead of creating a duplicate. `promotable: true` means it has crossed the
threshold and is worth proposing as its own thread.

Inputs: no named parameters. Returns: result

list_streamsA

List all streams (the top-level domains) in the user's Pensieve.

Inputs: no named parameters. Returns: result

promote_entityA

Promote a recurring entity into its own thread under a stream.

Propose this (with the user's OK) once an entity is `promotable` (see
`list_entities`). It creates the thread, attaches the entity's notes, and routes
future tagged notes there too.

Args:
    entity: Id of the entity to promote (from `list_entities`).
    stream: Id of the parent stream the thread should live under.

Inputs: entity (required), stream (required).

recentA

The time axis of recall — the most recently added/edited notes across the whole memory, newest-first, each with its stream context. Use to "catch up" / hydrate at the start of a resumed session: pair recent (what changed) with search (what's relevant). Distinct from search (relevance) and find_entities (names). Live notes only, capped with a truncated flag.

Args:
    since: Optional ISO date/datetime — only notes updated at/after it (e.g. "2026-06-01").
    limit: Max notes to return (default 20).

Inputs: limit, since.

remove_assetA

Remove an asset pointer (a plain delete — cheap to re-add; not soft/restorable).

Args:
    asset: Asset id to remove (asset-N).

Inputs: asset (required).

remove_entityA

Remove an entity (and its thread, if promoted). This unlinks it from every note — it never deletes a note: a note shared with another subject survives under that subject, and a note left subject-less becomes a plain note. Soft and reversible via restore_entity. Tell the user it's recoverable.

Args:
    entity: Id of the entity to remove (from `list_entities`).

Inputs: entity (required).

remove_noteA

Remove a note. Soft and reversible — bring it back with restore_note. An entity that loses its last live note disappears (derived). Tell the user it's recoverable.

Args:
    note: Id of the note to remove (e.g. "note-3").

Inputs: note (required).

remove_streamA

Remove a stream and its threads. Soft and reversible — bring it back with restore_stream. Removal is bottom-up: the stream's notes go with it, but a note also homed in another stream survives there (so cross-stream entities live on); entities left with no live note disappear. Tell the user it's recoverable.

Args:
    stream: Id of the stream to remove (from `list_streams`).

Inputs: stream (required).

restore_entityB

Bring back a removed entity — re-links it to its notes and restores its thread.

Args:
    entity: Id of the entity to restore.

Inputs: entity (required).

restore_noteA

Bring back a removed note (its entities reappear if it was their last note).

Args:
    note: Id of the note to restore (e.g. "note-3").

Inputs: note (required).

restore_streamA

Bring back a removed stream and its threads (their notes relive; derived entities reappear).

Args:
    stream: Id of the stream to restore.

Inputs: stream (required).

tag_noteA

Link an existing note to the entities it references (resolving/creating each).

Use when you spot a subject in a note that wasn't tagged at capture time. Resolve
against the registry first (`list_entities`/`find_entities`) to avoid duplicates.

Args:
    note: Id of the note to link (e.g. "note-3").
    entities: Each item is either {"id": "<existing-entity-id>"} (reuse) or
        {"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).

Inputs: note (required), entities (required).

unfile_noteA

Remove a note from one of its streams (it stays in the others). Refuses to remove a note's last home — use remove_note for that.

Args:
    note: Id of the note (e.g. "note-3").
    stream: Id of the stream to remove it from.

Inputs: note (required), stream (required).

untag_noteA

Remove an entity tag from a note — correct a mis-tag (e.g. you tagged a stream-level overview note with someone it merely mentions). If the entity is promoted, the note is also detached from its thread.

Args:
    note: Note id.
    entity: Entity id to unlink (from `list_entities`/`get_entity`).

Inputs: note (required), entity (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 26 tools

    Disambiguation5/5

    Every tool has a distinct purpose: notes, streams, entities, assets, tagging, filing, search, and recent. There is no overlap in functionality, making it easy for an agent to select the correct tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., add_note, create_stream, remove_entity), using lowercase with underscores throughout, which is predictable and readable.

    Tool Count4/5

    With 26 tools, the count is slightly on the higher side but still appropriate for a comprehensive memory management system covering streams, notes, entities, assets, and auxiliary operations like search and recent.

    Completeness4/5

    The tool set covers CRUD for all main resources (streams, notes, entities, assets) plus additional features like tagging, filing, promotion, search, and recent updates. Minor gaps like bulk operations exist but do not hinder core workflows.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with persistent, searchable memory that survives across conversations using semantic search, temporal versioning, and smart organization. Enables long-term context retention and cross-session continuity for AI assistants.
      14
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent, self-optimizing memory for AI agents, enabling them to remember preferences and context across sessions and share knowledge across multiple agents.
      4
      6 npm
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, cross-session memory for AI agents, allowing them to store and automatically retrieve information across different conversations and sessions without repeating context.
      54 npm
      179
      MIT