opencode-knowledge 0.4.2 → 0.5.0-next.1

package/README.md

@@ -1,24 +1,20 @@
-# opencode-knowledge
+# opencode-knowledge <img src="./assets/opencode-knowledge-logo.png" align="right" height="100"/>
 
-A comprehensive knowledge management system for OpenCode that provides:
-- **Role-based AI personalities** - Customize OpenCode's communication style
-- **Knowledge vault** - Organize coding standards, patterns, and best practices
-- **Tag-based search** - Quickly find relevant knowledge packages
-- **Session management** - Track loaded packages and optimize token usage
+An OpenCode plugin that dynamically loads knowledge from your vault on-demand. Add any content you want, the AI figures out what to load using tags and descriptions.
 
 ## Features
 
-### 🎭 Personality System
-Choose from different AI personas (staff engineer, frontend specialist, cthulhu, etc.) that influence how OpenCode communicates and approaches problems.
-
 ### 📚 Knowledge Vault
-Create a structured library of markdown-based knowledge packages with frontmatter metadata for easy discovery and loading.
+
+Organize coding standards, patterns, and best practices in markdown files with frontmatter metadata.
 
 ### 🔍 Smart Search
-Tag-based search system finds relevant knowledge packages based on your current task.
+
+Tag-based search finds relevant packages. The AI uses tags and descriptions to discover the right context.
 
 ### 💾 Session Persistence
-Tracks loaded packages across sessions and provides token-optimized context injection.
+
+Automatically indexes your vault on session start and tracks loaded packages.
 
 ---
 
@@ -46,25 +42,15 @@ Add the plugin to your OpenCode config:
 
 ## Quick Start
 
-### 1. Create Settings File
+### 1. Create Knowledge Vault
 
-Create `.opencode/knowledge/settings.json` in your project:
-
-```json
-{
-  "role": "staff_engineer"
-}
-```
-
-### 2. Create Knowledge Vault (Optional)
-
-If you want to use the knowledge management features, create a vault structure:
+Create the vault directory structure:
 
 ```bash
 mkdir -p .opencode/knowledge/vault/standards
 ```
 
-### 3. Create Your First Knowledge Package
+### 2. Create Your First Knowledge Package
 
 Create `.opencode/knowledge/vault/standards/code-conventions.md`:
 
@@ -81,39 +67,42 @@ category: standards
 # Code Conventions
 
 ## Naming
+
 - Use camelCase for variables and functions
 - Use PascalCase for classes and types
 
 ## Formatting
+
 - Use single quotes for strings
 - Line width: 100 characters
 - Always use semicolons
 ```
 
-### 4. Start OpenCode Session
+### 3. Start OpenCode Session
 
 The knowledge catalog is **automatically built on session start**. Just start a new session and the plugin will:
+
 - Scan your vault for packages
 - Build the searchable catalog
 - Inject knowledge map on first message
 
-### 5. Search and Load Knowledge
+### 4. Configure Personality (Optional)
 
-Search for packages by tags:
+Optionally configure OpenCode's communication style by creating `.opencode/knowledge/settings.json`:
 
-```
-knowledge_search [tags=typescript,conventions]
+```json
+{
+  "role": "staff_engineer"
+}
 ```
 
-Load packages into your session:
-
-```
-knowledge_load [paths=standards/code-conventions.md]
-```
+See the [Personalities](#personalities-optional) section for available options.
 
 ---
 
-## Available Personalities
+## Personalities (Optional)
+
+The plugin works perfectly fine without any personality configuration. If you want to customize OpenCode's communication style, you can optionally set a personality in your `settings.json`.
 
 ### staff_engineer
 
@@ -129,73 +118,6 @@ Ancient cosmic entity providing technical guidance with existential dread and co
 
 ---
 
-## Tools
-
-### knowledge_search
-
-Search for knowledge packages by tags.
-
-```
-knowledge_search [tags=typescript,react,testing]
-```
-
-**Parameters**: Comma-separated list of tags
-
-**Output**: Ranked list of matching packages with relevance scores
-
-**Example**:
-```
-Found 5 packages matching [typescript, react]:
-
-- **frontend/react-patterns.md** (75%)
-  Tags: typescript, react, patterns
-  Common React patterns and best practices
-
-- **standards/typescript-conventions.md** (50%)
-  Tags: typescript, conventions
-  TypeScript coding standards
-```
-
----
-
-### knowledge_load
-
-Load knowledge packages into the current session.
-
-```
-knowledge_load [paths=standards/code-conventions.md,frontend/react-patterns.md]
-```
-
-**Parameters**: Comma-separated list of package paths (relative to vault/)
-
-**Output**: Package content injected into context
-
-**Features**:
-- Deduplication (won't load same package twice)
-- Session tracking (remembers what's loaded)
-- Error handling (warns about missing packages)
-
----
-
-### knowledge_index
-
-Manually rebuild the knowledge catalog from your vault.
-
-```
-knowledge_index
-```
-
-**Output**: Summary of categories and packages indexed.
-
-**Note**: The catalog is **automatically built on session start**, so you rarely need this tool.
-
-**When to use**:
-- After adding packages mid-session
-- If auto-build failed during session start
-- To verify catalog contents
-
----
-
 ## Knowledge Package Format
 
 Knowledge packages are markdown files with YAML frontmatter:
@@ -212,8 +134,8 @@ required_knowledge:
   - other-package-1
   - other-package-2
 file_patterns:
-  - "*.tsx"
-  - "*.test.ts"
+  - '*.tsx'
+  - '*.test.ts'
 ---
 
 # Package Title
@@ -223,13 +145,37 @@ Your knowledge content here...
 
 ### Frontmatter Fields
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `tags` | Yes | Array of searchable tags |
-| `description` | Yes | Brief summary (used in search results) |
-| `category` | Yes | Category for organization (e.g., `frontend`, `backend`, `standards`) |
-| `required_knowledge` | No | Other packages that should be loaded first |
-| `file_patterns` | No | File patterns where this knowledge applies |
+| Field                | Required | Description                                                          |
+| -------------------- | -------- | -------------------------------------------------------------------- |
+| `tags`               | Yes      | Array of searchable tags                                             |
+| `description`        | Yes      | Brief summary (used in search results)                               |
+| `category`           | Yes      | Category for organization (e.g., `frontend`, `backend`, `standards`) |
+| `required_knowledge` | No       | Other packages that should be loaded automatically before this one (supports recursive dependencies)   |
+| `file_patterns`      | No       | File patterns where this knowledge applies (not yet implemented)     |
+
+### Dependency Loading
+
+The `required_knowledge` field enables automatic dependency loading. When you load a package, the plugin automatically loads all its dependencies first, recursively.
+
+**Example:**
+
+```markdown
+<!-- vault/personal/blog-writing.md -->
+---
+tags: [blog, writing]
+description: Blog writing guidelines
+category: personal
+required_knowledge:
+  - personal/author-context
+---
+```
+
+When AI loads `personal/blog-writing.md`, the plugin:
+1. Detects the `required_knowledge` dependency
+2. Automatically loads `personal/author-context.md` first
+3. Then loads `personal/blog-writing.md`
+
+This ensures the AI always has complete context without manual tracking. Dependencies can be nested (Package A requires B, B requires C), and the plugin handles circular dependencies gracefully.
 
 ---
 
@@ -239,9 +185,9 @@ Your knowledge content here...
 your-project/
 └── .opencode/
     └── knowledge/
-        ├── settings.json              # Plugin configuration
-        ├── knowledge.json             # Auto-generated catalog (gitignored)
-        ├── vault/                     # Your knowledge packages
+        ├── settings.json
+        ├── knowledge.json
+        ├── vault/
         │   ├── frontend/
         │   │   ├── react-patterns.md
         │   │   └── state-management.md
@@ -250,139 +196,13 @@ your-project/
         │   └── standards/
         │       ├── code-conventions.md
         │       └── testing-guide.md
-        └── tracker/                   # Session state (gitignored)
+        └── tracker/
             ├── session-state.jsonl
             └── knowledge-reads.jsonl
 ```
 
 ---
 
-## Token Optimization
-
-The plugin uses a single-phase approach for optimal token usage:
-
-### First Message Only
-- Shows full category-tag map (~500-1000 tokens depending on vault size)
-- Injects personality
-- Documents available tools with examples
-- Creates session state
-
-### Subsequent Messages
-- No knowledge context injected
-- LLM uses memory of first message
-- **100% token savings** on subsequent messages
-
-This approach provides significant token savings while ensuring the LLM has all the context it needs from the initial session setup.
-
----
-
-## Example Vault Structure
-
-Here's a recommended organization pattern:
-
-```
-vault/
-├── frontend/
-│   ├── react-patterns.md          # React best practices
-│   ├── state-management.md        # Redux, Context, etc.
-│   ├── component-testing.md       # Testing components
-│   └── accessibility.md           # A11y guidelines
-├── backend/
-│   ├── api-design.md              # REST/GraphQL patterns
-│   ├── database-patterns.md       # ORM, migrations
-│   └── error-handling.md          # Error handling strategies
-├── standards/
-│   ├── code-conventions.md        # General coding standards
-│   ├── git-workflow.md            # Branch strategy, commits
-│   └── code-review.md             # Review guidelines
-└── infrastructure/
-    ├── docker-patterns.md         # Container best practices
-    ├── ci-cd.md                   # Pipeline patterns
-    └── monitoring.md              # Observability
-```
-
----
-
-## Advanced Usage
-
-### Creating Cross-Referenced Packages
-
-Use `required_knowledge` to create dependency chains:
-
-```markdown
----
-tags:
-  - react
-  - advanced
-  - performance
-description: Advanced React performance optimization
-category: frontend
-required_knowledge:
-  - frontend/react-patterns
-  - standards/code-conventions
----
-
-# Advanced React Performance
-
-This builds on basic patterns...
-```
-
-### File Pattern Targeting
-
-Specify when knowledge applies:
-
-```markdown
----
-tags:
-  - testing
-  - jest
-description: Jest testing patterns
-category: frontend
-file_patterns:
-  - "*.test.ts"
-  - "*.test.tsx"
-  - "*.spec.ts"
----
-
-# Jest Testing Guide
-```
-
----
-
-## Troubleshooting
-
-### Settings file not found
-
-**Error**: `CONFIGURATION ERROR: Settings file not found`
-
-**Solution**: Create `.opencode/knowledge/settings.json` with:
-```json
-{
-  "role": "staff_engineer"
-}
-```
-
-### Personality not loading
-
-**Error**: `CONFIGURATION ERROR: Personality file not found`
-
-**Solution**: Verify the role name in `settings.json` matches an available personality (`staff_engineer` or `cthulhu`)
-
-### Catalog not found
-
-**Error**: `Knowledge catalog not found. Run knowledge_index first.`
-
-**Solution**: Run `knowledge_index` to build the catalog from your vault
-
-### Search returns no results
-
-**Possible causes**:
-1. Catalog is outdated → Run `knowledge_index`
-2. Tags don't match → Check tag spelling
-3. No packages with those tags → Add packages or adjust search
-
----
-
 ## Development
 
 ### Building
@@ -412,17 +232,6 @@ mise run format
 
 ---
 
-## Roadmap
-
-- [ ] Auto-load packages based on file patterns
-- [ ] Knowledge package dependencies resolution
-- [ ] Usage analytics and metrics
-- [ ] Export/import vault bundles
-- [ ] Knowledge package templates
-- [ ] VSCode extension for vault management
-
----
-
 ## Contributing
 
 Contributions welcome! Please:
@@ -434,6 +243,12 @@ Contributions welcome! Please:
 
 ---
 
+## Credits
+
+Special thanks to [@canyavall](https://github.com/canyavall) for being the creative mind that came up with the idea and initial working solution. He continues to improve this in the shadows to this day.
+
+---
+
 ## License
 
 MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/index.js

@@ -90,22 +90,15 @@ async function createSessionState(sessionId) {
     return;
   }
   const settingsPath = ".opencode/knowledge/settings.json";
-  if (!existsSync2(settingsPath)) {
-    throw new Error(`CONFIGURATION ERROR: Cannot create session state - settings file not found at ${settingsPath}`);
-  }
-  let role;
-  try {
-    const settingsContent = await readFile(settingsPath, "utf-8");
-    const settings = JSON.parse(settingsContent);
-    if (!settings.role) {
-      throw new Error(`CONFIGURATION ERROR: Cannot create session state - missing 'role' field in ${settingsPath}`);
-    }
-    role = settings.role;
-  } catch (error) {
-    if (error instanceof Error && error.message.includes("CONFIGURATION ERROR")) {
-      throw error;
+  let role = null;
+  if (existsSync2(settingsPath)) {
+    try {
+      const settingsContent = await readFile(settingsPath, "utf-8");
+      const settings = JSON.parse(settingsContent);
+      role = settings.role || null;
+    } catch (error) {
+      throw new Error(`Error reading settings.json: ${error}`);
     }
-    throw new Error(`Error reading settings.json: ${error}`);
   }
   const state = {
     role,
@@ -12720,19 +12713,53 @@ _...and ${results.length - 10} more results_`;
 import { readFileSync as readFileSync3, existsSync as existsSync5 } from "fs";
 import { join as join4 } from "path";
 var VAULT_DIR2 = ".opencode/knowledge/vault";
+function resolveDependencies(packagePath, vaultDir, loaded = new Set) {
+  if (loaded.has(packagePath)) {
+    return [];
+  }
+  loaded.add(packagePath);
+  const result = [];
+  const normalizedPath = packagePath.endsWith(".md") ? packagePath : `${packagePath}.md`;
+  const fullPath = join4(vaultDir, normalizedPath);
+  if (!existsSync5(fullPath)) {
+    return [];
+  }
+  try {
+    const content = readFileSync3(fullPath, "utf-8");
+    const { frontmatter } = parseFrontmatter(content);
+    if (frontmatter.required_knowledge && Array.isArray(frontmatter.required_knowledge)) {
+      for (const dep of frontmatter.required_knowledge) {
+        const depPath = dep.endsWith(".md") ? dep : `${dep}.md`;
+        const depPackages = resolveDependencies(depPath, vaultDir, loaded);
+        result.push(...depPackages);
+      }
+    }
+    result.push(normalizedPath);
+  } catch {
+    return [];
+  }
+  return result;
+}
 var knowledgeLoadTool = tool({
   description: "Load one or more knowledge packages from the vault into the current session context. The package content will be available for reference in subsequent responses.",
   args: {
     paths: tool.schema.string().describe("Comma-separated package paths relative to vault (e.g., 'standards/code-conventions.md,frontend/react-patterns.md')")
   },
   async execute(args) {
-    const packagePaths = args.paths.split(",").map((p) => p.trim()).filter(Boolean);
-    if (packagePaths.length === 0) {
+    const requestedPaths = args.paths.split(",").map((p) => p.trim()).filter(Boolean);
+    if (requestedPaths.length === 0) {
       return "No package paths provided";
     }
+    const allPackagePaths = new Set;
+    const loadedTracker = new Set;
+    for (const path2 of requestedPaths) {
+      const resolved = resolveDependencies(path2, VAULT_DIR2, loadedTracker);
+      resolved.forEach((p) => allPackagePaths.add(p));
+    }
     const loaded = [];
     const failed = [];
-    for (const packagePath of packagePaths) {
+    const packageArray = Array.from(allPackagePaths);
+    for (const packagePath of packageArray) {
       const fullPath = join4(VAULT_DIR2, packagePath);
       if (!existsSync5(fullPath)) {
         failed.push(`\u26A0\uFE0F  Package not found: ${packagePath}`);
@@ -12749,9 +12776,18 @@ ${content}`);
     }
     let output = "";
     if (loaded.length > 0) {
-      output += `\u2705 Loaded ${loaded.length}/${packagePaths.length} packages:
+      const totalCount = packageArray.length;
+      const requestedCount = requestedPaths.length;
+      const depsCount = totalCount - requestedCount;
+      if (depsCount > 0) {
+        output += `\u2705 Loaded ${loaded.length}/${totalCount} packages (${requestedCount} requested + ${depsCount} dependencies):
 
 `;
+      } else {
+        output += `\u2705 Loaded ${loaded.length}/${totalCount} packages:
+
+`;
+      }
       output += loaded.join(`
 
 ---
@@ -12813,7 +12849,6 @@ var opencodeKnowledge = async () => {
       try {
         const state = getSessionState(input.sessionID);
         if (state.isFirstPrompt) {
-          const personality = await loadPersonality(state.role);
           const vaultExists = existsSync6(".opencode/knowledge/vault");
           if (vaultExists) {
             const categoryTagMap = buildCategoryTagMap();
@@ -12835,15 +12870,18 @@ var opencodeKnowledge = async () => {
               messageID: input.messageID || ""
             });
           }
-          output.parts.push({
-            type: "text",
-            text: `## Role Context
+          if (state.role) {
+            const personality = await loadPersonality(state.role);
+            output.parts.push({
+              type: "text",
+              text: `## Role Context
 
 ${personality}`,
-            id: `personality-${Date.now()}`,
-            sessionID: input.sessionID,
-            messageID: input.messageID || ""
-          });
+              id: `personality-${Date.now()}`,
+              sessionID: input.sessionID,
+              messageID: input.messageID || ""
+            });
+          }
           updateSessionState(input.sessionID, {
             isFirstPrompt: false,
             categoriesShown: vaultExists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-knowledge",
-  "version": "0.4.2",
+  "version": "0.5.0-next.1",
   "description": "An OpenCode plugin",
   "author": {
     "name": "msegoviadev",