Skip to content
Back to search

pensieve

SkillWorks with Claude CodeGitHub

Project knowledge base and workflow router. knowledge/ caches explored file locations, module boundaries, and call chains for reuse; decisions/maxims are established architecture decisions and coding standards to follow, not relitigate; pipelines are reusable workflows; short-term/ stages new conclusions until promotion or deletion. Use self-improve after completing work to capture new insights. Provides seven tools: init, upgrade, migrate, doctor, self-improve, refine, and sync-instructions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kingkongshot--pensieve/badge.svg)](/listings/kingkongshot--pensieve)

HTML

<a href="/listings/kingkongshot--pensieve"><img src="/api/listings/kingkongshot--pensieve/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites: `git`, `bash`, `Python 3.8+`.

<details> <summary><b>Claude Code</b></summary>

# 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

</details>

<details> <summary><b>Other Clients (Cursor / General Agents, etc.)</b></summary>

Replace `<skill-path>` with the skill directory for your client (e.g., `~/.cursor/skills/pensieve`).

# 1. Global install (one-time only)
git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>

# 2. Initialize in your project
cd <your-project>
bash <skill-path>/.src/scripts/init-project-data.sh

</details>

System code is installed globally once; user data is stored per project in `<project>/.pensieve/`. Multiple projects share the same system code, each maintaining independent project knowledge.

<details> <summary><b>AI Agent Auto-Install Reference</b></summary>

When a user asks an AI agent to install Pensieve, the agent should follow this decision flow. Below, `SKILL_PATH` refers to the client-specific installation path (e.g., `~/.claude/skills/pensieve`).

**Step 1: Check global installation status**

SKILL_PATH="$HOME/.claude/skills/pensieve"  # Adjust per client

if [[ -d "$SKILL_PATH/.src" ]]; then
    echo "Pensieve is already globally installed, skipping clone"
else
    SKILL_PARENT="$(dirname "$SKILL_PATH")"
    # Check if parent directory is a git repo (some users sync configs with git)
    if git -C "$SKILL_PARENT/.." rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        git -C "$SKILL_PARENT/.." submodule add -b main https://github.com/kingkongshot/Pensieve.git "skills/pensieve"
    else
        git clone -b main https://github.com/kingkongshot/Pensieve.git "$SKILL_PATH"
    fi
    # Hooks are a Claude Code-specific feature; other clients skip this step
    # bash "$SKILL_PATH/.src/scripts/install-hooks.sh"
fi

**Step 2: Determine whether to run project initialization**

# If the current directory is the skill's parent config directory, don't auto-initialize project data
CURRENT_DIR="$(pwd)"
CONFIG_DIR="$(cd "$(dirname "$SKILL_PATH")/.." 2>/dev/null && pwd)"
if [[ "$CURRENT_DIR" == "$CONFIG_DIR" ]]; then
    echo "Current directory is the config directory, skipping project initialization. If you need to use Pensieve here, please specify explicitly."
    exit 0
fi

**Step 3: Check for legacy data and initialize**

HAS_LEGACY=0
for legacy_dir in .claude/skills/pensieve .agents/skills/pensieve skills/pensieve .claude/pensieve; do
    if [[ -d "$legacy_dir" ]] && [[ -d "$legacy_dir/maxims" || -d "$legacy_dir/decisions" || -d "$legacy_dir/knowledge" || -d "$legacy_dir/pipelines" ]]; then
        HAS_LEGACY=1
        break
    fi
done

if [[ "$HAS_LEGACY" -eq 1 ]]; then
    echo "Legacy Pensieve user data detected. Migrate to v2?"
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
    bash "$SKILL_PATH/.src/scripts/run-migrate.sh"
    bash "$SKILL_PATH/.src/scripts/run-doctor.sh" --strict
elif [[ -d .pensieve ]]; then
    echo "Pensieve is already initialized in the current project"
else
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
fi

> **Key takeaway**: Check global install first -> Determine if parent directory is a git repo to decide clone/submodule -> Skip project initialization for config directories -> Check for legacy data to decide init/migrate.

</details>

<details> <summary><b>Updating</b></summary>

# Update system code (one operation, all projects take effect)
cd <skill-path>
git pull --ff-only || { git fetch origin && git reset --hard "origin/$(git rev-parse --abbrev-ref HEAD)"; }

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: pensieve
  3. description: >-
  4. Project knowledge base and workflow router. knowledge/ caches explored file
  5. locations, module boundaries, and call chains for reuse; decisions/maxims are
  6. established architecture decisions and coding standards to follow, not
  7. relitigate; pipelines are reusable workflows; short-term/ stages new
  8. conclusions until promotion or deletion. Use self-improve after completing
  9. work to capture new insights. Provides seven tools: init, upgrade, migrate,
  10. doctor, self-improve, refine, and sync-instructions.
  11. ---
  12. # Pensieve
  13. Route user requests to the correct tool. When in doubt, confirm first.
  14. ## Routing
  15. - Init: Initialize the current project user-data directory and seed files. Tool spec: `.src/tools/init.md`.
  16. - Upgrade: Refresh Pensieve skill source code in the global git clone. Tool spec: `.src/tools/upgrade.md`.
  17. - Migrate: Run structural migration and legacy cleanup. Tool spec: `.src/tools/migrate.md`.
  18. - Doctor: Read-only scan of the current project user-data directory. Tool spec: `.src/tools/doctor.md`.
  19. - Self-Improve: Extract reusable conclusions and write them into user data. Tool spec: `.src/tools/self-improve.md`.
  20. - Refine: Refine the knowledge base with triage review and compression. Tool spec: `.src/tools/refine.md`.
  21. - Sync Instructions: Write existing pipeline short routes into `CLAUDE.md` / `AGENTS.md`. Tool spec: `.src/tools/sync-instructions.md`.
  22. - Graph View: Read `<project-root>/.pensieve/.state/pensieve-user-data-graph.md`.
  23. ## Project Data
  24. Project-level user data is stored in `<project-root>/.pensieve/`.
  25. See `.pensieve/state.md` for the current project's lifecycle state; see `.pensieve/.state/pensieve-user-data-graph.md` for the knowledge graph (read on demand).
README.md · README · 303 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # Pensieve
  3. **Give your AI agent a continuously growing project memory.**
  4. [![GitHub Stars](https://img.shields.io/github/stars/kingkongshot/Pensieve?color=ffcb47&labelColor=black&style=flat-square)](https://github.com/kingkongshot/Pensieve/stargazers)
  5. [![License](https://img.shields.io/badge/license-MIT-white?labelColor=black&style=flat-square)](LICENSE)
  6. [中文 README](https://github.com/kingkongshot/Pensieve/blob/zh/README.md)
  7. </div>
  8. **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.**
  9. | | CLAUDE.md / agents.md | Pensieve |
  10. |---|---|---|
  11. | Form | Single static file | Four-layer structured knowledge |
  12. | Maintenance | Manual writing, manual updates | Auto-accumulation, auto-alignment |
  13. | Scope | Project conventions | Conventions + decisions + facts + workflows |
  14. | Linking | Flat | Semantic links forming a knowledge graph |
  15. | Context usage | Full-text injection | Skill-based on-demand routing, minimal usage |
  16. ## Why Use Pensieve
  17. | Without | With |
  18. |---|---|
  19. | Have to re-explain project specs every time | Specs stored as maxims, loaded automatically |
  20. | Code review standards depend on mood | Review standards solidified into executable pipelines |
  21. | Repeat last week's mistake this week | Lessons auto-accumulated, skipped next time |
  22. | Forget why you designed it this way three months later | Decisions record context and alternatives |
  23. | Have to re-read docs to locate module boundaries every time | Knowledge caches exploration results, reuse directly |
  24. ## Self-Reinforcing Loop
  25. Pensieve doesn't just store documentation -- it makes every agent conversation more precise:
  26. - **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
  27. - **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
  28. - **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
  29. - **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?"
  30. You don't need to manually maintain the knowledge base -- daily development feeds it automatically:
  31. ```
  32. Develop --> Commit --> Review (pipeline)
  33. ^ |
  34. | <-- Auto-accumulate experience <-- |
  35. | v
  36. +-- maxim / decision / knowledge / pipeline
  37. ```
  38. - **During editing**: After Write/Edit, the knowledge graph syncs automatically (Claude Code triggers via hooks; other clients can manually run `self-improve`)
  39. - **During review**: Executes according to project pipelines, conclusions flow back as knowledge
  40. - **During retrospective**: `"Use pensieve to accumulate this experience"` -> Insights are written to the corresponding layer
  41. You steer the direction, Pensieve helps you avoid pitfalls.
  42. ## Four-Layer Knowledge Model
  43. | Layer | Type | What It Answers | Cross-project? |
  44. |---|---|---|---|
  45. | **MUST** | maxim | What must never be violated? | Yes -- holds across projects and languages |
  46. | **WANT** | decision | Why was this approach chosen? | No -- active trade-offs for the current project |
  47. | **HOW** | pipeline | How should this workflow run? | Depends |
  48. | **IS** | knowledge | What are the current facts? | No -- verifiable system facts |
  49. 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:
  50. <img src="docs/graph-overview.png" width="100%" alt="Pensieve knowledge graph overview" />
  51. <img src="docs/graph-detail.png" width="100%" alt="Pensieve knowledge graph detail" />
  52. See the detailed specifications under `.src/references/`: [maxims.md](.src/references/maxims.md), [decisions.md](.src/references/decisions.md), [knowledge.md](.src/references/knowledge.md), [pipelines.md](.src/references/pipelines.md).
  53. ## Five Tools
  54. | Tool | What It Does | Trigger Example |
  55. |---|---|---|
  56. | `init` | Create data directory, seed default content | "Initialize pensieve for me" |
  57. | `upgrade` | Refresh skill source code | "Upgrade pensieve" |
  58. | `migrate` | Migrate legacy data, align seed files | "Migrate to v2" |
  59. | `doctor` | Read-only scan, check structure and format | "Check if the data has any issues" |
  60. | `self-improve` | Extract insights from conversations and diffs, write to four-layer knowledge | "Accumulate this experience" |
  61. Tool boundaries and redirection rules: [tool-boundaries.md](.src/references/tool-boundaries.md).
  62. ## Looking for the Linus Prompt?
  63. 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.
  64. 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:
  65. | Type | Built-in Content | Effect |
  66. |---|---|---|
  67. | maxim | 4 Linus-style engineering principles | Agent avoids patchy code, simplifies before extending, and preserves existing behavior |
  68. | pipeline | Commit + code review + refactor | Every commit, review, and refactor checks against the standards and feeds conclusions back into knowledge |
  69. | knowledge | Code-taste review standard | "Good code" becomes executable |
  70. Try it: `"Use pensieve to review the code taste of recent commits"` or `"Use pensieve to commit local changes"`.
  71. ## Installation
  72. Prerequisites: `git`, `bash`, `Python 3.8+`.
  73. <details>
  74. <summary><b>Claude Code</b></summary>
  75. ```bash
  76. # 1. Global install (one-time only)
  77. git clone -b main https://github.com/kingkongshot/Pensieve.git ~/.claude/skills/pensieve
  78. # 2. Install hooks (recommended; auto-syncs knowledge graph after edits, auto-checks status on session start)
  79. bash ~/.claude/skills/pensieve/.src/scripts/install-hooks.sh
  80. # 3. Initialize in your project
  81. cd <your-project>
  82. bash ~/.claude/skills/pensieve/.src/scripts/init-project-data.sh
  83. ```
  84. </details>
  85. <details>
  86. <summary><b>Other Clients (Cursor / General Agents, etc.)</b></summary>
  87. Replace `<skill-path>` with the skill directory for your client (e.g., `~/.cursor/skills/pensieve`).
  88. ```bash
  89. # 1. Global install (one-time only)
  90. git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>
  91. # 2. Initialize in your project
  92. cd <your-project>
  93. bash <skill-path>/.src/scripts/init-project-data.sh
  94. ```
  95. </details>
  96. System code is installed globally once; user data is stored per project in `<project>/.pensieve/`. Multiple projects share the same system code, each maintaining independent project knowledge.
  97. <details>
  98. <summary><b>AI Agent Auto-Install Reference</b></summary>
  99. When a user asks an AI agent to install Pensieve, the agent should follow this decision flow. Below, `SKILL_PATH` refers to the client-specific installation path (e.g., `~/.claude/skills/pensieve`).
  100. **Step 1: Check global installation status**
  101. ```bash
  102. SKILL_PATH="$HOME/.claude/skills/pensieve" # Adjust per client
  103. if [[ -d "$SKILL_PATH/.src" ]]; then
  104. echo "Pensieve is already globally installed, skipping clone"
  105. else
  106. SKILL_PARENT="$(dirname "$SKILL_PATH")"
  107. # Check if parent directory is a git repo (some users sync configs with git)
  108. if git -C "$SKILL_PARENT/.." rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  109. git -C "$SKILL_PARENT/.." submodule add -b main https://github.com/kingkongshot/Pensieve.git "skills/pensieve"
  110. else
  111. git clone -b main https://github.com/kingkongshot/Pensieve.git "$SKILL_PATH"
  112. fi
  113. # Hooks are a Claude Code-specific feature; other clients skip this step
  114. # bash "$SKILL_PATH/.src/scripts/install-hooks.sh"
  115. fi
  116. ```
  117. **Step 2: Determine whether to run project initialization**
  118. ```bash
  119. # If the current directory is the skill's parent config directory, don't auto-initialize project data
  120. CURRENT_DIR="$(pwd)"
  121. CONFIG_DIR="$(cd "$(dirname "$SKILL_PATH")/.." 2>/dev/null && pwd)"
  122. if [[ "$CURRENT_DIR" == "$CONFIG_DIR" ]]; then
  123. echo "Current directory is the config directory, skipping project initialization. If you need to use Pensieve here, please specify explicitly."
  124. exit 0
  125. fi
  126. ```
  127. **Step 3: Check for legacy data and initialize**
  128. ```bash
  129. HAS_LEGACY=0
  130. for legacy_dir in .claude/skills/pensieve .agents/skills/pensieve skills/pensieve .claude/pensieve; do
  131. if [[ -d "$legacy_dir" ]] && [[ -d "$legacy_dir/maxims" || -d "$legacy_dir/decisions" || -d "$legacy_dir/knowledge" || -d "$legacy_dir/pipelines" ]]; then
  132. HAS_LEGACY=1
  133. break
  134. fi
  135. done
  136. if [[ "$HAS_LEGACY" -eq 1 ]]; then
  137. echo "Legacy Pensieve user data detected. Migrate to v2?"
  138. bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
  139. bash "$SKILL_PATH/.src/scripts/run-migrate.sh"
  140. bash "$SKILL_PATH/.src/scripts/run-doctor.sh" --strict
  141. elif [[ -d .pensieve ]]; then
  142. echo "Pensieve is already initialized in the current project"
  143. else
  144. bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
  145. fi
  146. ```
  147. > **Key takeaway**: Check global install first -> Determine if parent directory is a git repo to decide clone/submodule -> Skip project initialization for config directories -> Check for legacy data to decide init/migrate.
  148. </details>
  149. <details>
  150. <summary><b>Updating</b></summary>
  151. ```bash
  152. # Update system code (one operation, all projects take effect)
  153. cd <skill-path>
  154. git pull --ff-only || { git fetch origin && git reset --hard "origin/$(git rev-parse --abbrev-ref HEAD)"; }
  155. # Health check in your project (optional but recommended)
  156. cd <your-project>
  157. bash <skill-path>/.src/scripts/run-doctor.sh --strict
  158. ```
  159. `git pull --ff-only` works for normal updates. If the remote branch was force-pushed (e.g., after a squash and republish), ff-only will fail, and `fetch + reset` will sync local to the latest remote state. This is safe -- the skill directory only contains tracked system files; user data is in `<project>/.pensieve/` and won't be overwritten.
  160. Full installation, update, reinstall, and uninstall instructions: [skill-lifecycle.md](.src/references/skill-lifecycle.md).
  161. </details>
  162. <details>
  163. <summary><b>Upgrading from Legacy Versions</b></summary>
  164. If your Pensieve was installed at project level (code in `<project>/.claude/skills/pensieve/`), or installed via `claude plugin install`, you need to migrate to the v2 architecture:
  165. ```bash
  166. # 1. Global install system code (if not already installed)
  167. if [[ ! -d <skill-path> ]]; then
  168. git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>
  169. fi
  170. # 2. Install hooks (Claude Code only; other clients skip this)
  171. # bash <skill-path>/.src/scripts/install-hooks.sh
  172. # 3. Run migration in each project
  173. cd <your-project>
  174. bash <skill-path>/.src/scripts/init-project-data.sh
  175. bash <skill-path>/.src/scripts/run-migrate.sh
  176. bash <skill-path>/.src/scripts/run-doctor.sh --strict
  177. # 4. Uninstall old plugin (if applicable, Claude Code only)
  178. # claude plugin uninstall pensieve 2>/dev/null || true
  179. ```
  180. `run-migrate.sh` will automatically move user data (`maxims/`, `decisions/`, `knowledge/`, `pipelines/`) from legacy paths into `<project>/.pensieve/`, runtime state from `<project>/.state/` into `<project>/.pensieve/.state/`, clean up old graph files and README copies, then delete the legacy directories.
  181. </details>
  182. <details>
  183. <summary><b>Architecture Details</b></summary>
  184. ### Directory Structure
  185. ```text
  186. ~/.claude/skills/pensieve/ # User-level (single global install)
  187. ├── SKILL.md # Static routing file (tracked)
  188. ├── .src/ # System code, templates, references, core engine
  189. │ ├── core/
  190. │ ├── scripts/
  191. │ ├── templates/
  192. │ │ ├── agents/
  193. │ │ ├── knowledge/
  194. │ │ ├── maxims/
  195. │ │ └── pipelines/
  196. │ ├── references/
  197. │ └── tools/
  198. └── agents/ # agent/UI metadata
  199. <project>/.codex/skills/ # Project-level Codex skill (only for maintaining this repository)
  200. └── pensieve-sync-to-main/
  201. ├── SKILL.md
  202. └── agents/
  203. └── openai.yaml
  204. <project>/.pensieve/ # Project-level (per-project, can be version-controlled)
  205. ├── maxims/ # Engineering principles
  206. ├── decisions/ # Architectural decisions
  207. ├── knowledge/ # Cached exploration results
  208. ├── pipelines/ # Reusable workflows
  209. ├── state.md # Dynamic: lifecycle state + knowledge graph
  210. └── .state/ # Runtime artifacts (gitignored)
  211. ```
  212. `.src/manifest.json` is the anchor for the skill root directory -- scripts locate all paths through it.
  213. ### Design Principles
  214. - **Physical isolation of system code and user data** -- System code lives in `~/.claude/skills/pensieve/`, user data in `<project>/.pensieve/`; `git pull` to update the system can never touch project data
  215. - **Single source of truth for rules** -- Directories, key files, and migration paths are all defined in `.src/core/schema.json`
  216. - **Confirm before executing** -- When scope is unclear, ask first; don't auto-launch long workflows
  217. - **Read specs before writing data** -- Before creating any user data, read the format specifications in `.src/references/`
  218. </details>
  219. ## Community
  220. <img src="docs/QRCode.png" width="200" alt="QR Code" />
  221. ## License
  222. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.