kingkongshot/pensieve

2522 stars 质量 97 趋势 97

tore your decisions and principles. Claude reads them to make better choices.

概览

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

View this README on GitHub

安装

npx skillfish add kingkongshot/pensieve