You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(ai-knowledge): add Obsidian compatibility, /kb-query, /kb-organize, index & log (v2.3.3)
Add three new skills: /kb-query for querying the KB and filing synthesized
answers back as articles, /kb-obsidian for one-time migration to Obsidian-
compatible structure with _index.md/_log.md/folder reorganization, and
/kb-organize for standalone folder reorganization.
All existing /kb-* skills now maintain Obsidian-compatible ## Related body
sections with [[wiki-links]], store global learnings in _global-learnings.md
instead of inline CLAUDE.md, prefer subfolder organization for new files,
and conditionally update _index.md and _log.md.
Inspired by Karpathy's LLM Wiki pattern.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+46Lines changed: 46 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
8
8
## [Unreleased]
9
9
10
+
## [2.3.3] - 2026-04-05
11
+
12
+
### Added
13
+
14
+
#### AI-Knowledge Plugin (v1.3.0)
15
+
16
+
-`/kb-query` - Query the knowledge base and synthesize answers from multiple KB files
17
+
- Reads `_index.md` to find relevant pages, then drills into individual articles
18
+
- Synthesizes comprehensive answers with `[[wiki-link]]` citations to source KB files
19
+
- Flags contradictions between KB files and gaps in coverage
20
+
- Offers to **file answers back as new KB articles** so explorations compound into the knowledge base
21
+
- Filed answers include `type: synthesis`, `query`, and `sources` frontmatter fields for provenance
22
+
- Inspired by Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern
23
+
24
+
-`/kb-obsidian` - One-time migration to upgrade and make an existing KB Obsidian-compatible
25
+
- Adds `## Related` body sections with `[[wiki-links]]` for Obsidian graph view and link navigation
26
+
- Migrates inline `### Global Learnings` from CLAUDE.md to `docs/kb/_global-learnings.md`
27
+
- Generates `docs/kb/_index.md` — a categorized catalog of all KB articles with one-line summaries
28
+
- Creates `docs/kb/_log.md` — a chronological record of KB operations
29
+
- Offers to reorganize flat KB files into category folders (architecture/, conventions/, testing/, etc.)
30
+
- Audits and fixes frontmatter health issues
31
+
- Fully backwards-compatible — handles all older KB structures
32
+
33
+
-**`_index.md` — Knowledge Base Index** - Auto-generated, pinned catalog of all KB articles organized by category with one-line summaries. The LLM reads this first to find relevant pages before drilling into individual articles. Created by `/kb-init` and maintained by all `/kb-*` commands.
34
+
35
+
-**`_log.md` — Activity Log** - Append-only chronological record of KB operations (ingests, queries, prunes, etc.). Provides a timeline of how the knowledge base evolved. Created by `/kb-init` and appended to by all `/kb-*` commands.
36
+
37
+
-`/kb-organize` - Standalone folder reorganization for existing flat KB structures
38
+
- Analyzes flat KB files and suggests category folders based on tags and content
39
+
- Common categories: architecture/, conventions/, testing/, tools/, external/, domain/
40
+
- Preview-first — shows all proposed moves before executing
41
+
- Updates CLAUDE.md table paths and `_index.md` after reorganization
42
+
- Does not modify `[[wiki-links]]` (they resolve by name, not path)
43
+
44
+
### Changed
45
+
46
+
#### AI-Knowledge Plugin (v1.3.0)
47
+
48
+
-**Subfolder organization** - All `/kb-*` commands that create new KB files now prefer placing them in category subfolders (e.g., `docs/kb/architecture/`, `docs/kb/conventions/`, `docs/kb/testing/`) instead of flat in the root. Existing flat structures continue to work. `/kb-obsidian` offers to reorganize flat files into folders.
49
+
-**Obsidian-compatible Related Links** - All `/kb-*` commands that create or update KB files now maintain a `## Related` section at the end of the file body with `[[wiki-links]]` mirroring the `related` frontmatter field. Obsidian does not parse frontmatter values as navigable links, so body links are required for graph view edges and link navigation to work.
50
+
-**Global Learnings as dedicated KB file** - Global learnings are now stored in `docs/kb/_global-learnings.md` (a pinned KB file) instead of inline in CLAUDE.md's `### Global Learnings` section. This makes global learnings visible in Obsidian, searchable as a regular KB file, and eliminates duplication. Affects `/kb-init`, `/kb-learn`, `/kb-add`, `/kb-search`, `/kb-list`, and `/kb-prune`. Existing inline global learnings are preserved and can be migrated with `/kb-obsidian`.
51
+
-**Index and log maintenance** - All `/kb-*` commands that modify KB files now update `_index.md` and append to `_log.md` (conditionally — only if the files exist, for backwards compatibility).
52
+
-**Cross-reference cleanup now includes body links** - `/kb-remove` and `/kb-prune` now update both `related` frontmatter AND `## Related` body sections when cleaning up cross-references.
53
+
-**kb-prune detects out-of-sync Related sections** - Cross-reference integrity checks now flag KB files where the `## Related` body section doesn't match the `related` frontmatter.
54
+
-**kb-list and kb-search detect legacy global learnings** - These commands now check for and flag legacy inline `### Global Learnings` sections in CLAUDE.md, suggesting `/kb-obsidian` for migration.
Copy file name to clipboardExpand all lines: plugins/ai-knowledge/README.md
+27-4Lines changed: 27 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,14 @@ AI-powered knowledge base management for Claude Code. Capture conversation learn
6
6
7
7
Over time, you accumulate project-specific knowledge during Claude Code conversations: things that didn't work, best practices, client requirements, and codebase gotchas. This plugin captures that knowledge so future sessions benefit from it automatically.
8
8
9
-
Knowledge is stored in two layers:
10
-
-**KB files** (`docs/kb/*.md`): Topic-specific knowledge loaded contextually when working in relevant areas
11
-
-**Global Learnings** (in CLAUDE.md): Cross-cutting rules that apply everywhere
9
+
The knowledge base is a persistent, compounding wiki maintained by the LLM. It has three layers:
-**Index & Log** (`docs/kb/_index.md`, `docs/kb/_log.md`): Auto-generated catalog and chronological activity record
13
+
14
+
The knowledge base is fully **Obsidian-compatible** — open `docs/kb/` as an Obsidian vault to browse your knowledge graph, navigate between related topics, and visualize connections.
15
+
16
+
Inspired by Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern — the LLM does all the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base useful over time.
12
17
13
18
## Commands
14
19
@@ -26,7 +31,10 @@ Knowledge is stored in two layers:
26
31
|`/kb-list`| List all registered KB files with status, tags, dates, and cross-references |
27
32
|`/kb-search`| Search across KB files by keyword, topic, or tag (`tag:security`) |
28
33
|`/kb-prune`| Interactive cleanup: stale refs, duplicates, merges, frontmatter health |
34
+
|`/kb-query`| Query the KB and synthesize answers (optionally filed back as articles) |
29
35
|`/kb-auto`| Toggle automatic knowledge capture at end of conversations |
36
+
|`/kb-organize`| Reorganize flat KB files into category folders |
37
+
|`/kb-obsidian`| One-time upgrade for Obsidian compatibility, index, log, and folders |
30
38
31
39
## Getting Started
32
40
@@ -42,6 +50,8 @@ Knowledge is stored in two layers:
42
50
43
51
6. Periodically run `/kb-prune` to keep the knowledge base organized.
44
52
53
+
7. Run `/kb-obsidian` to make an existing KB Obsidian-compatible, then open `docs/kb/` as an Obsidian vault.
54
+
45
55
## How It Works
46
56
47
57
The Knowledge Base table in CLAUDE.md tells Claude Code which KB files to read based on what you're working on:
Cross-references (`related`) create a knowledge graph -- when Claude loads one KB file and sees related references, it knows to also consult the linked files for full context.
77
87
88
+
### Obsidian Compatibility
89
+
90
+
KB files also include a `## Related` section at the bottom of the file body with `[[wiki-links]]` mirroring the frontmatter:
91
+
92
+
```markdown
93
+
## Related
94
+
95
+
-[[api-conventions]]
96
+
-[[auth-patterns]]
97
+
```
98
+
99
+
This is required because Obsidian does not parse frontmatter values as navigable links. The body `[[wiki-links]]` enable Obsidian's graph view edges and click-to-navigate between related topics. All `/kb-*` commands maintain this section automatically.
Copy file name to clipboardExpand all lines: plugins/ai-knowledge/skills/kb-absorb/SKILL.md
+18-3Lines changed: 18 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,10 @@ disable-model-invocation: true
8
8
9
9
You are a knowledge base migration specialist. Your job is to analyze a project's existing documentation — CLAUDE.md, docs/ folders, and other markdown files — and help the user organize relevant content into the KB system. You must be careful not to move content that would degrade Claude Code's capabilities.
10
10
11
+
## Obsidian-Compatible Related Links
12
+
13
+
When a KB file has `related` entries in its frontmatter, you MUST also include a `## Related` section at the **end** of the file body with the same references as `[[wiki-links]]`. This enables Obsidian graph view and link navigation. Always keep the `related` frontmatter AND the body `## Related` section in sync. If there are no related files, omit the section entirely.
14
+
11
15
## Instructions
12
16
13
17
**CRITICAL**: This command MUST NOT accept any arguments. Ignore any text provided after the command.
@@ -58,7 +62,7 @@ Documentation Analysis
58
62
These sections are topic-specific and could be loaded contextually:
After all migrations, scan the newly created KB files for related topics and add `related` cross-references in frontmatter where appropriate.
139
+
After all migrations, scan the newly created KB files for related topics and add `related` cross-references in frontmatter where appropriate. Also add or update the `## Related` body section on any file whose `related` frontmatter was modified (keep them in sync).
140
+
141
+
### Phase 5: Update Index and Log
142
+
143
+
1.**Update `docs/kb/_index.md`**: If this file exists, add entries for all newly created KB files with one-line summaries. Update `last-updated` in its frontmatter.
144
+
2.**Append to `docs/kb/_log.md`**: If this file exists, append:
When a KB file has `related` entries in its frontmatter, you MUST also include a `## Related` section at the **end** of the file body with the same references as `[[wiki-links]]`. This enables Obsidian graph view and link navigation. Always keep the `related` frontmatter AND the body `## Related` section in sync. If there are no related files, omit the `## Related` section entirely.
29
+
26
30
## Instructions
27
31
28
32
### Step 1: Get the Learning
@@ -51,8 +55,8 @@ Based on the learning content, existing KB structure, and frontmatter tags, dete
51
55
- Header: "KB Location"
52
56
- Options should include (as applicable):
53
57
- Matching existing KB file(s) if the learning fits an existing topic — prioritize tag matches (e.g., "Append to `docs/kb/api-conventions.md` (tags: api, rest)")
54
-
- A suggested new KB file if no existing file fits (e.g., "Create new file: `docs/kb/deployment.md`")
55
-
- "Global Learnings (CLAUDE.md)" if the learning is cross-cutting
58
+
- A suggested new KB file if no existing file fits — prefer subfolder organization (e.g., "Create new file: `docs/kb/tools/deployment.md`"). Use existing folder structure as a guide.
59
+
- "Global Learnings (`docs/kb/_global-learnings.md`)" if the learning is cross-cutting
56
60
- "Custom location" for the user to specify their own path
57
61
58
62
If the user selects "Custom location", ask a follow-up:
@@ -88,7 +92,7 @@ If saving to a new KB file, gather metadata:
88
92
7. Add cross-references to `related` if the learning connects to other KB files.
89
93
90
94
#### If creating a new KB file:
91
-
1. Create the file with frontmatterand standard structure:
95
+
1. Create the file with frontmatter, content, and related links:
92
96
```markdown
93
97
---
94
98
tags: [{confirmed tags}]
@@ -106,19 +110,36 @@ If saving to a new KB file, gather metadata:
106
110
## Key Rules
107
111
108
112
- {The learning, concise and actionable}
113
+
114
+
## Related
115
+
116
+
-[[{related-kb-file}]]
109
117
```
118
+
Only include the `## Related` section if there are related files. It must be the last section.
110
119
2. Update the CLAUDE.md Knowledge Base table:
111
120
- Remove placeholder row if present.
112
121
- Add new row with Topic, File path, and When to Load (use "Always (pinned)" if pinned).
113
122
- Keep table sorted alphabetically by Topic.
114
-
3. Add reverse cross-references: if the new file relates to existing KB files, add `[[new-file]]` to those files' `related` frontmatter and update their `last-updated`.
123
+
3. Add reverse cross-references: if the new file relates to existing KB files, add `[[new-file]]` to those files' `related` frontmatter, update their `## Related` body section to match, and update their `last-updated`.
115
124
116
125
#### If adding to Global Learnings:
117
-
1. Append as a bullet point under `### Global Learnings` in CLAUDE.md.
118
-
2. Remove placeholder text if present.
119
-
3. Deduplicate against existing entries.
126
+
1. Read `docs/kb/_global-learnings.md`. If it doesn't exist, create it with frontmatter (`tags: [global, cross-cutting]`, `pinned: true`, today's dates) and a `# Global Learnings` heading.
127
+
2. Append as a bullet point under `## Key Rules`.
128
+
3. Remove placeholder text if present ("_No global learnings captured yet..._").
129
+
4. Deduplicate against existing entries.
130
+
5. Update `last-updated` in frontmatter to today's date.
131
+
6. Ensure `_global-learnings.md` is registered in the CLAUDE.md Knowledge Base table as: `| Global Learnings | docs/kb/_global-learnings.md | Always (pinned) |`
132
+
133
+
### Step 6: Update Index and Log
134
+
135
+
1.**Update `docs/kb/_index.md`**: If this file exists, add or update the entry for the modified file with a one-line summary. Update `last-updated` in its frontmatter.
136
+
2.**Append to `docs/kb/_log.md`**: If this file exists, append:
0 commit comments