Skip to content
Back to search

second-brain-for-agents

MarketplaceWorks with Claude CodeGitHub

A markdown vault the agent files into, compiles into a cited wiki and cleans up with your approval.

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/mavrin-xv--second-brain-for-agents/badge.svg)](/listings/mavrin-xv--second-brain-for-agents)

HTML

<a href="/listings/mavrin-xv--second-brain-for-agents"><img src="/api/listings/mavrin-xv--second-brain-for-agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

You:   save this https://example.com/newsletter-teardown and compile it
Agent: (capture) raw/2026-02-10-email-teardown-of-a-pottery-newsletter.md
       (wiki-ingest) plan: 1 source page, update concepts/kiln-drop-emails,
       create entities/kiln-supply-co. Go?
You:   go
Agent: wrote wiki/sources/pottery-newsletter-teardown.md, updated 2 pages,
       index.md and log.md. 1 open question: weekly digest vs per-firing email.

Next morning, from the bundled sample vault (real output):

$ python3 skills/dreaming/scripts/dream_digest.py status --pending
D-20261120-01  pending  merge    Kiln drop email / Kiln drop emails
D-20261120-02  pending  create   concepts/drop-scarcity
D-20261120-03  pending  promote  announce the drop time two days ahead, not the same morning
D-20261120-04  pending  decide   Beginner glaze workshop on Saturdays
D-20261120-05  pending  review   2 wiki pages waiting for review

$ python3 skills/dreaming/scripts/dream_digest.py decide D-20261120-02 kill --note "covered in kiln-drop-emails"
D-20261120-02: killed

Full run with every script: [examples/walkthrough.md](examples/walkthrough.md).

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.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "second-brain-for-agents",
  3. "owner": {
  4. "name": "Artem Mavrin",
  5. "url": "https://github.com/mavrin-xv"
  6. },
  7. "plugins": [
  8. {
  9. "name": "second-brain-for-agents",
  10. "source": "./",
  11. "description": "Agent-maintained markdown vault: capture, wiki ingest, search, graph, health checks, nightly dreaming with human approval.",
  12. "version": "0.1.0"
  13. }
  14. ]
  15. }
README.md · README · 144 lines
  1. ![second-brain-for-agents](assets/banner.png)
  2. # second-brain-for-agents
  3. **A markdown vault your AI agent keeps for you: it files what you send, compiles sources into a cited wiki, searches before it answers, and proposes a nightly cleanup that you approve or kill.**
  4. Notes pile up faster than anyone reads them. Six months in, the "second brain" is a warehouse: duplicate pages, links to nothing, sources nobody summarised, and an agent that answers from memory instead of from your notes.
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. ![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex%20%7C%20any%20SKILL.md%20agent-black)
  7. ![Python](https://img.shields.io/badge/scripts-Python%203.8%2B%20stdlib-green)
  8. ![Search](https://img.shields.io/badge/search-qmd%20or%20built--in%20BM25-lightgrey)
  9. ```bash
  10. git clone https://github.com/mavrin-xv/second-brain-for-agents && cd second-brain-for-agents
  11. ./install.sh # or: ./install.sh --project
  12. ```
  13. <!-- install-notes:start -->
  14. Other ways in: as a Claude Code plugin, run `/plugin marketplace add mavrin-xv/second-brain-for-agents` and then `/plugin install second-brain-for-agents@second-brain-for-agents`. For Codex or another agent that reads `SKILL.md`, copy the folders under `skills/` into its skills directory. On Windows, run `install.sh` from Git Bash or WSL and type `py -3` where these docs say `python3`.
  15. <!-- install-notes:end -->
  16. Then tell your agent: `set up a vault in ~/notes/vault` and `save this: https://example.com/some-article`.
  17. ---
  18. ## What it solves
  19. | Pain | What the pack does |
  20. |---|---|
  21. | "Where do I put this?" every time | One routing table in `SCHEMA.md`; the agent files thoughts, todos, ideas, decisions and links into the right folder with frontmatter |
  22. | Saved links never get read | `capture` stores the page as markdown in `raw/`; `wiki-ingest` compiles it into a source page plus the concept and entity pages it touches, every claim cited |
  23. | The agent answers from its training data, not your notes | `vault-search` runs before answering or writing: qmd if installed, a built-in BM25 ranker if not |
  24. | Twin pages and links to nothing | `new_note.py` refuses to create a concept or entity that already exists; `vault-health` finds broken links, duplicates, orphans |
  25. | No idea how the notes connect | `knowledge-graph` writes `GRAPH.md` with clusters, most-linked pages, orphans and broken links |
  26. | An agent that rewrites its own memory unsupervised | `dreaming` only writes a proposal file at night. You approve or kill each item in the morning; killed items never come back |
  27. | Ideas sit at "new" for months | Health flags stuck ideas; dreaming asks for a test-or-kill decision |
  28. ## What's inside
  29. | Skill | What it does | Say |
  30. |---|---|---|
  31. | `vault-setup` | Creates or tops up the vault: folders, `SCHEMA.md` routing rules, `index.md`, `log.md`, templates | "set up a vault", "start a second brain", "fix my vault layout" |
  32. | `capture` | Files a thought, todo, idea, decision or link verbatim, with frontmatter and a duplicate check; fetches URLs into `raw/` | "save this", "note that", "capture", "remember this link" |
  33. | `wiki-ingest` | Compiles raw sources into cited wiki pages (Karpathy LLM wiki), plan first, contradictions kept as open questions | "ingest", "compile my sources", "process the raw folder" |
  34. | `vault-search` | Searches the vault before answering; files good answers back into `wiki/answers/` | "what do my notes say about", "search the vault", "have I written about" |
  35. | `knowledge-graph` | Builds the link graph, writes `GRAPH.md`, keeps "Referenced by" footers | "build the graph", "what links to", "find orphans" |
  36. | `vault-health` | 14 checks with errors, warnings and info, a score, and fixes shown before they are applied | "check the vault", "lint my notes", "vault health" |
  37. | `dreaming` | Nightly scan that proposes merges, new pages, rules and decisions; human approves or kills | "dream", "nightly review", "what should I merge" |
  38. Each skill folder has a `SKILL.md`, `references/` for the long parts, and stdlib Python scripts with `--help`. `templates/nightly.sh` runs the night job. `examples/sample-vault/` is a small invented vault with planted problems to try everything on.
  39. ## Quick start
  40. ```text
  41. You: save this https://example.com/newsletter-teardown and compile it
  42. Agent: (capture) raw/2026-02-10-email-teardown-of-a-pottery-newsletter.md
  43. (wiki-ingest) plan: 1 source page, update concepts/kiln-drop-emails,
  44. create entities/kiln-supply-co. Go?
  45. You: go
  46. Agent: wrote wiki/sources/pottery-newsletter-teardown.md, updated 2 pages,
  47. index.md and log.md. 1 open question: weekly digest vs per-firing email.
  48. ```
  49. Next morning, from the bundled sample vault (real output):
  50. ```text
  51. $ python3 skills/dreaming/scripts/dream_digest.py status --pending
  52. D-20261120-01 pending merge Kiln drop email / Kiln drop emails
  53. D-20261120-02 pending create concepts/drop-scarcity
  54. D-20261120-03 pending promote announce the drop time two days ahead, not the same morning
  55. D-20261120-04 pending decide Beginner glaze workshop on Saturdays
  56. D-20261120-05 pending review 2 wiki pages waiting for review
  57. $ python3 skills/dreaming/scripts/dream_digest.py decide D-20261120-02 kill --note "covered in kiln-drop-emails"
  58. D-20261120-02: killed
  59. ```
  60. Full run with every script: [examples/walkthrough.md](examples/walkthrough.md).
  61. ## How it works
  62. ```
  63. you ──"save this"──► capture ──► inbox/ ideas/ decisions/ daily/ (your words, verbatim)
  64. │
  65. └─ URL ─► raw/ (immutable source)
  66. │
  67. ▼
  68. wiki-ingest ──► wiki/sources wiki/concepts wiki/entities
  69. │ (agent-owned, cited, reviewed: false)
  70. ▼
  71. index.md + log.md
  72. question ──► vault-search (qmd / BM25) ──► answer ──► wiki/answers/ (if worth keeping)
  73. night ──► knowledge-graph ──► vault-health ──► dreaming scan ──► proposals/dream-DATE.md
  74. morning ─► you: approve / kill ──► agent applies approved items only ──► log.md
  75. ```
  76. Three layers, as in the LLM wiki pattern: `raw/` is never edited, `wiki/` belongs to the agent, `SCHEMA.md` holds the rules both of you follow. More in [docs/how-it-works.md](docs/how-it-works.md).
  77. ## Configure
  78. | Setting | Where | Default |
  79. |---|---|---|
  80. | Vault location | `VAULT_DIR` env var or `--vault` on every script | `./vault` |
  81. | Protected folders (never read or linked by scripts) | `SCHEMA.md`, `protected:` line | `private` |
  82. | Stale thresholds (inbox, raw, ideas) | `SCHEMA.md`, `stale_*_days:` lines | 7, 3, 30 |
  83. | Backlink footer threshold | `SCHEMA.md`, `footer_threshold:` | 3 inbound links |
  84. | Search engine | install qmd (`npm install -g @tobilu/qmd`) or nothing | built-in BM25 |
  85. | Clean HTML extraction | install defuddle, then `fetch_source.py --defuddle` | built-in stripper |
  86. | Candidates per night | `dream_digest.py scan --max N` | 10 |
  87. ## Honest limits
  88. - The scripts find structure, not meaning. Duplicate detection compares titles; two pages that say the same thing under different titles need the agent's judgement step.
  89. - The built-in fetcher does not run JavaScript. Pages behind a login or rendered by script come back short; paste the text with `--stdin`.
  90. - The plural fold is English-only and crude (`emails` = `email`, `glass` stays `glass`).
  91. - Footers are the only change scripts make to your pages, and only with `--footers`. Everything else is written by the agent, so its quality is the model's quality. `reviewed: false` exists so you can see what you have not checked.
  92. - Tested on the bundled sample vault, on Windows with Git Bash and Python 3.12. Not yet run on macOS or Linux, and not on vaults with tens of thousands of pages; the graph script reads every file on each run.
  93. - qmd setup is documented but its vector search needs a model download on first `qmd embed`.
  94. ## Credits
  95. - Based on / inspired by Andrej Karpathy's LLM wiki note, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f (no license stated; the raw / wiki / schema split and the ingest, query, lint operations come from here)
  96. - Search: qmd by Tobi Lutke, https://github.com/tobi/qmd (MIT)
  97. - Extraction: defuddle by kepano, https://github.com/kepano/defuddle (MIT); vault skill conventions from https://github.com/kepano/obsidian-skills (MIT)
  98. - Inspired by https://github.com/Astro-Han/karpathy-llm-wiki (MIT) and https://github.com/kfchou/wiki-skills (severity tiers, showing a fix before applying it)
  99. - Ideas only, no code: https://github.com/basicmachines-co/basic-memory (AGPL-3.0), https://github.com/thedotmack/claude-mem
  100. - Skill format: https://github.com/anthropics/skills
  101. ## Contributing
  102. Bug reports with a small vault that reproduces them are the most useful thing. See [CONTRIBUTING.md](CONTRIBUTING.md) and the checks in [AGENTS.md](AGENTS.md).
  103. <!-- author:start -->
  104. ## Author
  105. Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
  106. <!-- author:end -->
  107. ## License
  108. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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