pensieve-mcp
Pensieve is a personal, agent-driven long-term memory system backed by SQLite that lets you capture, organize, and recall information across AI sessions. It provides full CRUD operations across streams, notes, entities, and assets:
Streams (top-level domains): create, list, get, edit, remove, and restore.
Notes (core information units): add to streams with entity tags, edit, remove/restore, file/unfile across streams, and tag/untag entities.
Entities (people, orgs, topics): list, fuzzy-search (find_entities), get full details, edit name/aliases, promote to threads, and remove/restore.
Threads: created by promoting a recurring entity into its own thread under a stream.
Recall / Search:
Full-text search across note content and asset pointers, stemmed and relevance-ranked.
Recent notes ordered by time, optionally filtered by date.
Assets (by-reference pointers to files, repos, URLs, images, docs): add with a usage hint, list by stream/thread/note, and remove.
Pensieve
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:
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.
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.
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.
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.
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 — |
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+.
Recommended: from PyPI
Pensieve is a standard MCP server, so the quickest way in is pipx
(or uv):
pipx install pensieve-mcp # or: uv tool install pensieve-mcpThis 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-mcpFor 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/fetchflows) 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 # bothinstall.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 storeThis 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 toolsadd_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).
searchA
Search the memory's content for recall — note prose (stemmed, relevance-ranked)
and asset pointers (matched on hint/label/location, never their contents). Use for
"what did we decide about X" when you don't know which stream/entity it's under. This is
distinct from find_entities (which matches names). Returns live results only, capped
with a *_truncated flag; it never follows an asset pointer.
Args:
query: Words to match (OR-ed; relevance floats full matches to the top).
Inputs: query (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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory shared across Claude, ChatGPT, Grok and other MCP clients.
Hosted memory for AI agents: save what your agent learns and recall it in the next session.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 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-

Mnemexa MCPofficial
AlicenseAqualityDmaintenanceProvides persistent, self-optimizing memory for AI agents, enabling them to remember preferences and context across sessions and share knowledge across multiple agents.46 npmISC- AlicenseNot gradedqualityBmaintenanceProvides persistent, cross-session memory for AI agents, allowing them to store and automatically retrieve information across different conversations and sessions without repeating context.54 npm179MIT
- AlicenseAqualityDmaintenanceProvides persistent memory for AgentChat agents with swim-lane summarization and self-evolving persona, enabling context management and persona mining across conversations.10MIT