Pensieve: turning a CLAUDE.md into a memory that writes itself

A knowledge base that treats markdown as a database

The one-sentence description in the README is the whole pitch: Pensieve is a self-growing CLAUDE.md that runs as a skill, with minimal context usage and compatibility across AI tools that support skills.

The problem it attacks is specific and familiar. A single `CLAUDE.md` or `agents.md` file is one static blob that gets injected into context in full, that you have to maintain by hand, and that only ever records conventions. The README puts the two side by side in five rows. Form goes from a single static file to four-layer structured knowledge. Maintenance goes from manual writing and manual updates to auto-accumulation and auto-alignment. Scope grows from project conventions to conventions plus decisions plus facts plus workflows. Linking goes from flat to semantic links forming a knowledge graph. And context usage goes from full-text injection to skill-based on-demand routing described as minimal usage.

That last row is the architectural argument. If everything about a project lives in one file, every conversation pays for all of it. Split the file into layers and let the agent route to the layer the question needs, and the cost of having a large memory drops.

The repository is small and shell-first: MIT licensed, written in Shell, 2,514 stars, 251 forks, 6 open issues, default branch `main`, last pushed 2026-05-08. There are no GitHub releases at all, which tells you something about how versioning works here and also about what stability guarantees you are getting.

Four layers, because facts and rules have different half-lives

The core idea is a four-layer model, and each layer is a type rather than a folder name.

MUST is a maxim: what must never be violated. The table marks this layer as the one that holds across projects and languages, which is the right call, since the things that are never acceptable do not change when you change repositories.

WANT is a decision: why was this approach chosen. Not cross-project, because active trade-offs belong to the current project and go stale when the trade-off changes.

HOW is a pipeline: how should this workflow run. The table marks cross-project status as depends, which is honest, since a commit workflow can travel and a deploy workflow usually cannot.

IS is knowledge: what are the current facts, described as verifiable system facts and explicitly not cross-project. Facts expire, and putting them anywhere near maxims is how documentation becomes misleading.

The layers are connected by three kinds of semantic link, `based-on`, `leads-to` and `related`, which combine into a directed graph of project knowledge. The README includes overview and detail renders of that graph, and the detailed specs live under `.src/references/` as `maxims.md`, `decisions.md`, `knowledge.md` and `pipelines.md`. Four files for four layers is a good sign about how little ceremony each layer actually has.

The loop is meant to be self-reinforcing. During editing, the knowledge graph syncs automatically after Write or Edit. During review, project pipelines execute and conclusions flow back as knowledge. During retrospective, an explicit request writes insights into the appropriate layer. The documented trigger phrases are concrete: checking the accuracy of a plan against maxims and decisions before it executes, locating a module entry point from cached exploration results instead of searching globally, tracing which workflows a refactor affects by following link chains, and committing code without re-asking about style or module boundaries.

Five commands and one philosophy that used to be a prompt

The tool surface is five entries in a table, each with a trigger example, which is small enough to remember.

`init` creates the data directory and seeds default content. `upgrade` refreshes the skill source code. `migrate` migrates legacy data and aligns seed files, with the example given as migrating to v2. `doctor` performs a read-only scan that checks structure and format. `self-improve` extracts insights from conversations and diffs and writes them into the four layers. Redirection rules between tools are documented separately in `tool-boundaries.md` under the same references directory.

`doctor` being read-only is the detail worth keeping in mind. You can inspect the accumulated state without changing it, which matters for a tool whose whole premise is writing to your repository during normal work.

The project has a history here that the README is upfront about. Pensieve was initially known for a Linus Torvalds-style guiding prompt built on good taste, don't break userspace, and paranoid about simplicity. That philosophy is no longer a standalone prompt. It is now built in as three categories of executable content: four Linus-style engineering principles seeded into the maxim layer so the agent avoids patchy code, simplifies before extending, and preserves existing behaviour; a commit plus code review plus refactor pipeline so those standards get checked and the conclusions feed back into knowledge; and a code-taste review standard in the knowledge layer, on the reasoning that good code should be executable rather than aspirational. The README suggests trying it with requests like reviewing the code taste of recent commits, or committing local changes.

The stated value is that taste is no longer something you re-explain per session. Whether four principles survive contact with a real codebase is an empirical question, and six open issues suggests the project is still small enough that you can read the discussion before committing to it.

Installing it, and the one caveat in the compatibility claim

Prerequisites are `git`, `bash` and Python 3.8 or newer. The Claude Code path is three steps, and the middle one is marked recommended rather than required:

# 1. Global install (one-time only)
git clone -b main https://github.com/kingkongshot/Pensieve.git ~/.claude/skills/pensieve

# 2. Install hooks (recommended; auto-syncs knowledge graph after edits, auto-checks status on session start)
bash ~/.claude/skills/pensieve/.src/scripts/install-hooks.sh

# 3. Initialize in your project
cd <your-project>
bash ~/.claude/skills/pensieve/.src/scripts/init-project-data.sh

Other clients get the same shape with the path swapped. The README asks you to replace `<skill-path>` with the skill directory for your client, giving `~/.cursor/skills/pensieve` as the example, and then run the same `init-project-data.sh` from your project. System code installs globally once, and user data lives separately.

Here is the caveat, and it is the one place where the marketing sentence and the documentation diverge. The claim is compatibility with all AI tools that support skills, and the two-step install for other clients does contain the same script. But the automatic part of the loop, the sync after edits and the status check at session start, is delivered by install-hooks.sh, which is a Claude Code mechanism. The README says as much elsewhere: Claude Code triggers it via hooks, while other clients run `self-improve` manually. So on a non-Claude client you get the four layers and the graph, and you supply the automation yourself.

Worth noting alongside that: there are no tagged releases, and the `upgrade` tool is described as refreshing the skill source code. Since the install is a `git clone -b main`, you are tracking a moving branch, not a pinned version, which is also why `migrate` and its v2 example exist.

What to expect from a 2,500-star shell repository

The tree is compact and tells you where the substance lives: `.src/` for implementation and references, `SKILL.md` at the root as the skill entry point, `agents/` for agent-side definitions, `docs/` for the graph images the README embeds, `.codex/` for Codex-side integration, plus `CHANGELOG.md`, `LICENSE` and the README itself. A `CHANGELOG.md` with no releases to tag against is a normal setup for a skill that versions by cloning a branch.

The documentation is bilingual, with a Chinese README maintained on a `zh` branch, which is a reasonable signal about the project's origin community. Topics are not set on the repository, so discovery is entirely through search and the README's comparison table.

Two things worth checking before you rely on it. First, the graph is only worth something if it gets maintained, and maintenance here is a mix of hooks and manual requests; nothing in the documentation forces the discipline. Second, the tool writes into your repository during ordinary editing and review, so the sensible first move is `doctor`, which is read-only, to see the structure and format of whatever is already there. After that, `self-improve` on a real piece of work is the honest test of whether the four layers earn their place.

For a project that began as a good-taste prompt and became a structured memory system, the trajectory is more interesting than the star count. The question it is really asking is whether agent memory should be a document you maintain or a structure you operate. Pensieve has taken a clear position, and given that it is 2,514 stars and 251 forks on a Shell codebase with no releases, it is a position worth reading even if you run something else.

Editorial conclusion

Pensieve's real contribution is not the memory store, any agent can be told to remember things. It is the split between what must never be violated, what was chosen and why, how a workflow should run, and what is currently true. Each of those four has a different half-life, and collapsing them into one markdown file is why project documentation stops being true within a month. The cost is real too: hooks that write to your repository, a graph that only stays useful if it is actually maintained, no tagged releases, and a stated compatibility claim that holds more precisely for Claude Code than for every other client. Treat the four-layer model as the idea worth borrowing even if you never install the skill, and if you do install it, start with doctor to see what the accumulated state actually looks like before you trust it in a commit.

Frequently asked questions

Official sources

1. Issues
2. kingkongshot/Pensieve on GitHub
3. License: MIT
4. README