tore your decisions and principles. Claude reads them to make better choices.
Overview
Pensieve doesn't just store documentation -- it makes every agent conversation more precise: - -- "Use pensieve to check the accuracy of this plan" -> Automatically cross-references maxims and decisions; plans that violate architectural conventions are intercepted before execution - -- "Use pensieve to locate the entry point of the payment module" -> Knowledge contains previous exploration results, reuse directly without global search, saving tokens and time - -- "Use pensieve to analyze which workflows this refactoring will affect" -> Four-layer knowledge forms a graph through semantic links, following association chains to discover design intent and dependencies - -- "Use pensieve conventions to commit code" -> Conventions and decisions are already accumulated, no more asking "what style?" or "where's the boundary?
README
In one sentence: Pensieve is a self-growing CLAUDE.md that runs as a skill – minimal context usage, compatible with all AI tools that support skills.
| CLAUDE.md / agents.md | Pensieve | |
|---|---|---|
| Form | Single static file | Four-layer structured knowledge |
| Maintenance | Manual writing, manual updates | Auto-accumulation, auto-alignment |
| Scope | Project conventions | Conventions + decisions + facts + workflows |
| Linking | Flat | Semantic links forming a knowledge graph |
| Context usage | Full-text injection | Skill-based on-demand routing, minimal usage |
Why Use Pensieve
| Without | With |
|---|---|
| Have to re-explain project specs every time | Specs stored as maxims, loaded automatically |
| Code review standards depend on mood | Review standards solidified into executable pipelines |
| Repeat last week’s mistake this week | Lessons auto-accumulated, skipped next time |
| Forget why you designed it this way three months later | Decisions record context and alternatives |
| Have to re-read docs to locate module boundaries every time | Knowledge caches exploration results, reuse directly |
Self-Reinforcing Loop
Pensieve doesn’t just store documentation – it makes every agent conversation more precise:
- Validate AI-generated plans –
"Use pensieve to check the accuracy of this plan"-> Automatically cross-references maxims and decisions; plans that violate architectural conventions are intercepted before execution - Narrow the exploration scope –
"Use pensieve to locate the entry point of the payment module"-> Knowledge contains previous exploration results, reuse directly without global search, saving tokens and time - Establish implicit connections –
"Use pensieve to analyze which workflows this refactoring will affect"-> Four-layer knowledge forms a graph through semantic links, following association chains to discover design intent and dependencies - Reduce repeated confirmations –
"Use pensieve conventions to commit code"-> Conventions and decisions are already accumulated, no more asking “what style?” or “where’s the boundary?”
You don’t need to manually maintain the knowledge base – daily development feeds it automatically:
Develop --> Commit --> Review (pipeline)
^ |
| <-- Auto-accumulate experience <-- |
| v
+-- maxim / decision / knowledge / pipeline
- During editing: After Write/Edit, the knowledge graph syncs automatically (Claude Code triggers via hooks; other clients can manually run
self-improve) - During review: Executes according to project pipelines, conclusions flow back as knowledge
- During retrospective:
"Use pensieve to accumulate this experience"-> Insights are written to the corresponding layer
You steer the direction, Pensieve helps you avoid pitfalls.
Four-Layer Knowledge Model
| Layer | Type | What It Answers | Cross-project? |
|---|---|---|---|
| MUST | maxim | What must never be violated? | Yes – holds across projects and languages |
| WANT | decision | Why was this approach chosen? | No – active trade-offs for the current project |
| HOW | pipeline | How should this workflow run? | Depends |
| IS | knowledge | What are the current facts? | No – verifiable system facts |
Layers are connected through three types of semantic links: based-on / leads-to / related. As usage accumulates, Pensieve automatically builds a directed graph of project knowledge:
See the detailed specifications under .src/references/: maxims.md, decisions.md, knowledge.md, pipelines.md.
Five Tools
| Tool | What It Does | Trigger Example |
|---|---|---|
init |
Create data directory, seed default content | “Initialize pensieve for me” |
upgrade |
Refresh skill source code | “Upgrade pensieve” |
migrate |
Migrate legacy data, align seed files | “Migrate to v2” |
doctor |
Read-only scan, check structure and format | “Check if the data has any issues” |
self-improve |
Extract insights from conversations and diffs, write to four-layer knowledge | “Accumulate this experience” |
Tool boundaries and redirection rules: tool-boundaries.md.
Looking for the Linus Prompt?
Pensieve was initially known for a Linus Torvalds-style guiding prompt – using “good taste”, “don’t break userspace”, and “paranoid about simplicity” to constrain agent behavior.
That engineering philosophy is still at the core of Pensieve, but it’s no longer an isolated prompt. It’s now built in as executable principles, so the agent has “good taste” from day one:
| Type | Built-in Content | Effect |
|---|---|---|
| maxim | 4 Linus-style engineering principles | Agent avoids patchy code, simplifies before extending, and preserves existing behavior |
| pipeline | Commit + code review + refactor | Every commit, review, and refactor checks against the standards and feeds conclusions back into knowledge |
| knowledge | Code-taste review standard | “Good code” becomes executable |
Try it: "Use pensieve to review the code taste of recent commits" or "Use pensieve to commit local changes".
Installation
Prerequisites: git, bash, Python 3.8+.
System code is installed globally once; user data is stored per project in /.pensieve/. Multiple projects share the same system code, each maintaining independent project knowledge.
Community
License
MIT
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add kingkongshot/pensieve