Skip to content
Back to search

obsidian-knowledge-agent

MarketplaceWorks with Claude CodeGitHub

A self-evolving knowledge agent for Obsidian: from a one-line capture to a full course build, for any subject. Matches structure to the material, fits your vault, and learns your conventions from every run.

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/michael-ovo--obsidian-knowledge-agent/badge.svg)](/listings/michael-ovo--obsidian-knowledge-agent)

HTML

<a href="/listings/michael-ovo--obsidian-knowledge-agent"><img src="/api/listings/michael-ovo--obsidian-knowledge-agent/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.

These steps run a script from the network that findsafeskills does not scan.

The most effort it'll ever ask of you. **Same two-command flow for Claude Code and OpenAI Codex** — add the marketplace, then install.

**Claude Code**

/plugin marketplace add Michael-OvO/obsidian-knowledge-agent
/plugin install obsidian-knowledge@obsidian-knowledge-agent

**OpenAI Codex**

codex plugin marketplace add Michael-OvO/obsidian-knowledge-agent
codex plugin add obsidian-knowledge@obsidian-knowledge-agent

You get the ingestion skill, all [12 commands](#commands), and the self-evolution hooks. Then run `/obsidian-knowledge:setup` in your vault — **empty folder or an existing vault, it adapts** — or just start talking to it.

<details> <summary><b>Don't have Codex yet?</b></summary>

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # macOS / Linux
npm install -g @openai/codex                           # …or npm
brew install --cask codex                              # …or Homebrew

Windows: `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"` · or grab the [IDE extension](https://developers.openai.com/codex/ide). </details>

Prefer no plugin? Seed any folder with the rule files + learning state — works with **any** agent:

curl -fsSL https://raw.githubusercontent.com/Michael-OvO/obsidian-knowledge-agent/main/install.sh | bash -s -- /path/to/your/vault

**First run:** say *"save this link"* for one clean note, or drop a syllabus into `Inbox/` and say *"organize my inbox"*. Don't like what it did? Run `reflect`, approve the rule diff with `evolve`, and it won't repeat the mistake.

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 · 22 lines

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

  1. {
  2. "name": "obsidian-knowledge-agent",
  3. "owner": {
  4. "name": "Michael-OvO",
  5. "url": "https://github.com/Michael-OvO"
  6. },
  7. "description": "A self-evolving knowledge agent for Obsidian: from a one-line capture to a full course build, for any subject. Matches structure to the material, fits your vault, and learns your conventions from every run.",
  8. "plugins": [
  9. {
  10. "name": "obsidian-knowledge",
  11. "source": "./plugins/obsidian-knowledge",
  12. "description": "Self-evolving knowledge agent for Obsidian. From a quick capture to a full course build, for any subject — it matches structure to the material, fits your vault's conventions, writes notes that teach, and reflects on each run to improve its own rules.",
  13. "version": "2.2.0",
  14. "author": { "name": "Michael-OvO", "url": "https://github.com/Michael-OvO" },
  15. "homepage": "https://github.com/Michael-OvO/obsidian-knowledge-agent",
  16. "repository": "https://github.com/Michael-OvO/obsidian-knowledge-agent",
  17. "license": "MIT",
  18. "keywords": ["obsidian", "knowledge-management", "pkm", "self-evolving", "notes", "skills"],
  19. "category": "productivity"
  20. }
  21. ]
  22. }
README.md · README · 232 lines · 6 findings marked

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

  1. <div align="center">
  2. <a href="https://github.com/Codex-Lab-Org"><img src="docs/assets/codex-logo.svg" width="120" height="120" alt="Codex Lab"></a>
  3. # Obsidian Knowledge Agent
  4. **Talk to your vault. It does the rest.**
  5. You drop it in. It files, it teaches, and it remembers how you like your notes.
  6. [![Part of Codex Lab](https://img.shields.io/badge/Part%20of-Codex%20Lab-6E40C9?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCAzMiAzMiIgcm9sZT0iaW1nIiBhcmlhLWxhYmVsPSJPcGVuQUkgQ29kZXgiPjx0aXRsZT5PcGVuQUkgQ29kZXg8L3RpdGxlPjxwYXRoIGQ9Ik0yMi4zNTYgMTkuNzk3SDE3LjE3TTkuNjYyIDEyLjI5bDEuOTc5IDMuNTc2YS41MTEuNTExIDAgMCAxLS4wMDUuNTA0bC0xLjk3NCAzLjQwOU0zMC43NTggMTZjMCA4LjE1LTYuNjA3IDE0Ljc1OC0xNC43NTggMTQuNzU4LTguMTUgMC0xNC43NTgtNi42MDctMTQuNzU4LTE0Ljc1OEMxLjI0MiA3Ljg1IDcuODUgMS4yNDIgMTYgMS4yNDJjOC4xNSAwIDE0Ljc1OCA2LjYwOCAxNC43NTggMTQuNzU4WiIgc3Ryb2tlPSIjZmZmZmZmIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS13aWR0aD0iMi40ODQiLz48L3N2Zz4%3D&labelColor=1f1f1f)](https://github.com/Codex-Lab-Org)
  7. [![Plugin: Claude Code + Codex](https://img.shields.io/badge/plugin-Claude%20Code%20%2B%20Codex-6E40C9)](#install)
  8. [![Works with](https://img.shields.io/badge/works%20with-Claude%20·%20Codex%20·%20Cursor-1f6feb)](#works-with-any-agent)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  10. [![GitHub stars](https://img.shields.io/github/stars/Michael-OvO/obsidian-knowledge-agent?style=social)](https://github.com/Michael-OvO/obsidian-knowledge-agent)
  11. </div>
  12. ---
  13. Point any agentic assistant at your Obsidian vault and **talk to it** — *"save this link"*, *"organize my inbox"*, *"ingest the syllabus in Inbox"*. It reads how your vault is already organized, matches effort to the material, and writes notes that actually *teach*: a clean one-liner for a quick save, or a fully scaffolded collection with a concept-graph canvas for a whole course.
  14. Then it does what a prompt-pack can't: **it reflects on every run and rewrites its own rules.** Each correction you make becomes a durable, reviewable lesson in your git history — applied automatically next time. No fine-tuning. No black box.
  15. ## Before / after
  16. You ask your agent to *"make notes on this paper."* It writes a flat summary to `notes.md` at the repo root, picks a filename you'll never find again, and moves on.
  17. With the agent:
  18. ```text
  19. # you: "save this"
  20. ML/Papers/Attention Is All You Need.md ← filed, not dumped
  21. tags: [transformers, attention] ← your frontmatter, matched
  22. see also: [[Self-Attention]], [[Positional Encoding]] ← wired into what you know
  23. ```
  24. A teaching-grade note in your vault's own conventions — the key equation in LaTeX, a runnable block, a diagram where each genuinely helps. And the next correction you make becomes a rule it keeps.
  25. More in [`examples/`](examples/).
  26. ## Install
  27. The most effort it'll ever ask of you. **Same two-command flow for Claude Code and OpenAI Codex** — add the marketplace, then install.
  28. **Claude Code**
  29. ```text
  30. /plugin marketplace add Michael-OvO/obsidian-knowledge-agent
  31. ```
  32. ```text
  33. /plugin install obsidian-knowledge@obsidian-knowledge-agent
  34. ```
  35. **OpenAI Codex**
  36. ```text
  37. codex plugin marketplace add Michael-OvO/obsidian-knowledge-agent
  38. ```
  39. ```text
  40. codex plugin add obsidian-knowledge@obsidian-knowledge-agent
  41. ```
  42. You get the ingestion skill, all [12 commands](#commands), and the self-evolution hooks. Then run `/obsidian-knowledge:setup` in your vault — **empty folder or an existing vault, it adapts** — or just start talking to it.
  43. <details>
  44. <summary><b>Don't have Codex yet?</b></summary>
  45. ```bash
  46. curl -fsSL https://chatgpt.com/codex/install.sh | sh # macOS / Linux
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 72 on GitHub
  47. npm install -g @openai/codex # …or npm
  48. brew install --cask codex # …or Homebrew
  49. ```
  50. Windows: `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"` · or grab the [IDE extension](https://developers.openai.com/codex/ide).
  51. </details>
  52. Prefer no plugin? Seed any folder with the rule files + learning state — works with **any** agent:
  53. ```bash
  54. curl -fsSL https://raw.githubusercontent.com/Michael-OvO/obsidian-knowledge-agent/main/install.sh | bash -s -- /path/to/your/vault
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 83 on GitHub
  55. ```
  56. **First run:** say *"save this link"* for one clean note, or drop a syllabus into `Inbox/` and say *"organize my inbox"*. Don't like what it did? Run `reflect`, approve the rule diff with `evolve`, and it won't repeat the mistake.
  57. ## How it works — it picks the altitude
  58. No rigid pipeline forced on every input. Before it writes, it stops at the altitude that fits the material:
  59. ```text
  60. 1. A link or a thought → one clean note, filed in the right place
  61. 2. A handful of sources → a few notes + a light index
  62. 3. A whole syllabus or book → the full scaffold: indexes, navigation,
  63. a quality pass, and a concept-graph canvas
  64. ```
  65. It escalates only when the material asks for it — and it **fits the vault you're already in** (your folders, your naming, your frontmatter) instead of imposing a taxonomy. The academic branches (`School/`, `ML/`, `Quant/`) are just defaults for an empty vault; a work vault's `Projects/ Meetings/ People/` works just as well.
  66. ## Commands
  67. You rarely need these — just talk to it (*"research X"*, *"organize my inbox"*, *"check my vault for broken links"*). But when you want a command, here's the set. Run `/obsidian-knowledge:help` for an in-tool guide, or `:help <command>` for detail.
  68. | Command | What it does |
  69. | --- | --- |
  70. | `/obsidian-knowledge:setup [domains]` | Set this folder up as a vault — **adapts to an empty folder or an existing vault**. |
  71. | `/obsidian-knowledge:capture <thing>` | Save one quick, clean note in the right place. |
  72. | `/obsidian-knowledge:ingest [what]` | Build notes from `Inbox/` (or what you point at) at the right altitude. |
  73. | `/obsidian-knowledge:research <topic>` | Research a topic from the web and write teaching notes with sources. |
  74. | `/obsidian-knowledge:log <text>` | Append a timestamped line to today's daily log. |
  75. | `/obsidian-knowledge:polish [note]` | Improve existing notes in place (defaults to recently changed). |
  76. | `/obsidian-knowledge:refactor <change>` | Reorganize safely and rewire every affected wikilink. |
  77. | `/obsidian-knowledge:doctor [folder]` | Health check: broken links, orphans, missing frontmatter. |
  78. | `/obsidian-knowledge:clean [message]` | Commit changed notes, clear processed Inbox (with approval), push. |
  79. | `/obsidian-knowledge:reflect` | Capture lessons from recent work and propose rule updates. |
  80. | `/obsidian-knowledge:evolve` | Review and approve the agent's proposed rule changes. |
  81. | `/obsidian-knowledge:help [command]` | Show everything the agent can do; add a name for detail. |
  82. **Try this first:** `setup` → drop a source in `Inbox/` → `ingest` → `polish` → `reflect`.
  83. ## Why it's different — it self-evolves
  84. Most "AI notes" tools run the same way forever. This one **compounds**: the more you use it, the more it matches *your* vault's taste.
  85. It borrows the file-based learning model from self-evolving agents like [Hermes](https://github.com/NousResearch/hermes-agent) — the agent rewrites its own markdown, never its weights — and specializes it for knowledge ingestion:
  86. ```mermaid
  87. flowchart LR
  88. A[Recall<br/>read .agents/learned/] --> B[Ingest → Compile → Distribute<br/>the 6-phase pipeline]
  89. B --> C[Reflect<br/>journal + propose rule diff]
  90. C -->|you approve the diff| D[(.agents/learned/<br/>conventions · examples · skills)]
  91. D -.auto-recalled next run.-> A
  92. ```
  93. - **Your conventions & style corrections** → `.agents/learned/conventions.md`, proposed as a **git diff you approve**.
  94. - **How to classify *your* kind of inputs** → `.agents/learned/examples.md` — few-shot, capped, recent-wins.
  95. - **Playbooks for brand-new source types** → `.agents/learned/skills/*.md` — one per input shape.
  96. - **The full run history** → `.agents/learned/journal.md` — **append-only**, never rewritten.
  97. **Two-tier autonomy:** the journal is written freely; changes to the agent's *rules* are always surfaced as a diff for your approval — so it learns without quietly drifting. See [`.agents/self-evolution.md`](.agents/self-evolution.md) for the full loop.
  98. 👉 **See it learn:** [`examples/EVOLUTION.md`](examples/EVOLUTION.md) walks a real before/after — a correction becomes a rule, and the next run gets it right on its own. Your vault gets sharper every time you use it. That's the whole idea.
  99. ## What makes the notes good
  100. - **Teaching-note style** ([`.agents/style-guide.md`](.agents/style-guide.md)) — notes read like something you'd revisit, with the machinery kept off-stage.
  101. - **Artifacts that teach** — deep notes reach for a runnable code block, a LaTeX equation, or a Mermaid diagram where each genuinely helps (and skip the filler).
  102. - **Concept-graph canvas** — collections of 3+ units get a [JSON-Canvas](https://jsoncanvas.org/) map linking each concept to the units where it appears.
  103. - **Link integrity** — a real [link validator](plugins/obsidian-knowledge/scripts/validate_links.py) flags broken wikilinks before commit, resolving image/PDF embeds, block (`^`) and heading (`#`) anchors, and aliases the way Obsidian does, and ignoring links inside code. Runs in the pipeline and in CI.
  104. - **Parallel workers** — note-writing and the quality pass fan out across multiple agents.
  105. The full pipeline (recall → ingest → compile → distribute → reflect) lives in [`.agents/ingestion-workflow.md`](.agents/ingestion-workflow.md). Lighter captures run only the stages they need.
  106. ## Works with any agent
  107. The whole pipeline is plain markdown (`AGENTS.md` + `.agents/`), so it runs in **Claude Code, Codex, Cursor, or any agent that reads `AGENTS.md`** — self-evolution included (the hooks are a convenience, not a requirement).
  108. ```bash
  109. # Into an Obsidian vault (AGENTS.md + .agents/ + a seeded .agents/learned/ + Inbox/)
  110. curl -fsSL https://raw.githubusercontent.com/Michael-OvO/obsidian-knowledge-agent/main/install.sh | bash -s -- /path/to/your/vault
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 161 on GitHub
  111. # As a bare skill (into ~/.claude/skills/)
  112. curl -fsSL https://raw.githubusercontent.com/Michael-OvO/obsidian-knowledge-agent/main/install.sh | bash -s -- --skill
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 164 on GitHub
  113. # Both at once
  114. curl -fsSL https://raw.githubusercontent.com/Michael-OvO/obsidian-knowledge-agent/main/install.sh | bash -s -- --both /path/to/your/vault
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 167 on GitHub
  115. ```
  116. <details>
  117. <summary>From a clone instead</summary>
  118. ```bash
  119. git clone https://github.com/Michael-OvO/obsidian-knowledge-agent
  120. cd obsidian-knowledge-agent
  121. ./install.sh /path/to/your/vault # vault files + learning state
  122. ./install.sh --skill # bare skill
  123. ./install.sh --both /path/to/vault # both
  124. ```
  125. </details>
  126. ## FAQ
  127. **Will it touch my existing notes?** Only with your approval. It reads your vault before it writes, and clears the `Inbox/` only when you say so.
  128. **I already have a big vault — do I start over?** No. `setup` adapts: it reads your existing folders, naming, and frontmatter, imposes nothing, and fills only the gaps (learning state, an `Inbox/`, a dashboard).
  129. **Does it need a config file?** No. Drop in the plugin (or the rule files) and talk to it.
  130. **Does it work without the plugin?** Yes — it's just markdown (`AGENTS.md` + `.agents/`). The plugin only adds the commands and the recall/reflect hooks.
  131. **What if it gets my taste wrong?** Run `reflect`, approve the rule diff with `evolve`, and it won't repeat the mistake.
  132. ## Repo layout
  133. ```text
  134. obsidian-knowledge-agent/ # one repo, a Claude Code AND Codex marketplace
  135. ├── .claude-plugin/marketplace.json # Claude Code marketplace manifest
  136. ├── .agents/plugins/marketplace.json # Codex marketplace manifest
  137. ├── plugins/obsidian-knowledge/ # the plugin
  138. │ ├── .claude-plugin/plugin.json # Claude plugin manifest
  139. │ ├── .codex-plugin/plugin.json # Codex plugin manifest (marketplace card)
  140. │ ├── skills/obsidian-knowledge/ # the ingestion skill (+ synced references/)
  141. │ ├── commands/ # the 12-command suite
  142. │ ├── hooks/hooks.json # SessionStart recall + Stop reflect-nudge
  143. │ └── scripts/ # recall.sh · reflect-nudge.sh · validate_links.py
  144. ├── AGENTS.md + .agents/ # tool-agnostic source of truth (any agent)
  145. │ └── self-evolution.md # the learning loop
  146. ├── examples/ # worked run + EVOLUTION.md before/after demo
  147. └── install.sh # one-line installer for vaults & the skill
  148. ```
  149. `.agents/` is the single source of truth; [`scripts/sync-skill.sh`](scripts/sync-skill.sh) mirrors it into the plugin's skill references.
  150. ## Customize
  151. - **Branches:** edit the branch table in `AGENTS.md` and `.agents/vault-architecture.md` to match your domains.
  152. - **Style:** tune `.agents/style-guide.md` (which artifacts technical notes reach for, the default note shapes) for your subjects.
  153. - **Conventions:** frontmatter, naming, math, and canvas rules live in `.agents/obsidian-conventions.md`.
  154. - **What it has learned:** read or prune `.agents/learned/` anytime — it's just markdown.
  155. ## Contributing
  156. Issues and PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates the plugin/marketplace manifests and runs the link checker on every PR.
  157. ## Part of Codex Lab
  158. This project is part of **[Codex Lab](https://github.com/Codex-Lab-Org)** — explore the rest of the lab on [GitHub](https://github.com/Codex-Lab-Org).
  159. ## License
  160. 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.