opencode-knowledge 0.4.2-next.1 → 0.4.2

package/README.md

@@ -1,20 +1,24 @@
-# opencode-knowledge <img src="./assets/opencode-knowledge-logo.png" align="right" height="100"/>
+# opencode-knowledge
 
-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.
+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
 
 ## Features
 
-### 📚 Knowledge Vault
+### 🎭 Personality System
+Choose from different AI personas (staff engineer, frontend specialist, cthulhu, etc.) that influence how OpenCode communicates and approaches problems.
 
-Organize coding standards, patterns, and best practices in markdown files with frontmatter metadata.
+### 📚 Knowledge Vault
+Create a structured library of markdown-based knowledge packages with frontmatter metadata for easy discovery and loading.
 
 ### 🔍 Smart Search
-
-Tag-based search finds relevant packages. The AI uses tags and descriptions to discover the right context.
+Tag-based search system finds relevant knowledge packages based on your current task.
 
 ### 💾 Session Persistence
-
-Automatically indexes your vault on session start and tracks loaded packages.
+Tracks loaded packages across sessions and provides token-optimized context injection.
 
 ---
 
@@ -42,15 +46,25 @@ Add the plugin to your OpenCode config:
 
 ## Quick Start
 
-### 1. Create Knowledge Vault
+### 1. Create Settings File
+
+Create `.opencode/knowledge/settings.json` in your project:
+
+```json
+{
+  "role": "staff_engineer"
+}
+```
+
+### 2. Create Knowledge Vault (Optional)
 
-Create the vault directory structure:
+If you want to use the knowledge management features, create a vault structure:
 
 ```bash
 mkdir -p .opencode/knowledge/vault/standards
 ```
 
-### 2. Create Your First Knowledge Package
+### 3. Create Your First Knowledge Package
 
 Create `.opencode/knowledge/vault/standards/code-conventions.md`:
 
@@ -67,42 +81,39 @@ 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
 ```
 
-### 3. Start OpenCode Session
+### 4. 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
 
-### 4. Configure Personality (Optional)
+### 5. Search and Load Knowledge
 
-Optionally configure OpenCode's communication style by creating `.opencode/knowledge/settings.json`:
+Search for packages by tags:
 
-```json
-{
-  "role": "staff_engineer"
-}
+```
+knowledge_search [tags=typescript,conventions]
 ```
 
-See the [Personalities](#personalities-optional) section for available options.
+Load packages into your session:
 
----
+```
+knowledge_load [paths=standards/code-conventions.md]
+```
 
-## 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`.
+## Available Personalities
 
 ### staff_engineer
 
@@ -118,6 +129,73 @@ 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:
@@ -134,8 +212,8 @@ required_knowledge:
   - other-package-1
   - other-package-2
 file_patterns:
-  - '*.tsx'
-  - '*.test.ts'
+  - "*.tsx"
+  - "*.test.ts"
 ---
 
 # Package Title
@@ -145,13 +223,13 @@ 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 (not yet implemented)     |
+| 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 |
 
 ---
 
@@ -161,9 +239,9 @@ Your knowledge content here...
 your-project/
 └── .opencode/
     └── knowledge/
-        ├── settings.json
-        ├── knowledge.json
-        ├── vault/
+        ├── settings.json              # Plugin configuration
+        ├── knowledge.json             # Auto-generated catalog (gitignored)
+        ├── vault/                     # Your knowledge packages
         │   ├── frontend/
         │   │   ├── react-patterns.md
         │   │   └── state-management.md
@@ -172,13 +250,139 @@ your-project/
         │   └── standards/
         │       ├── code-conventions.md
         │       └── testing-guide.md
-        └── tracker/
+        └── tracker/                   # Session state (gitignored)
             ├── 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
@@ -208,6 +412,17 @@ 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:
@@ -219,12 +434,6 @@ 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,15 +90,22 @@ async function createSessionState(sessionId) {
     return;
   }
   const settingsPath = ".opencode/knowledge/settings.json";
-  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}`);
+  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;
     }
+    throw new Error(`Error reading settings.json: ${error}`);
   }
   const state = {
     role,
@@ -12806,6 +12813,7 @@ 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();
@@ -12827,18 +12835,15 @@ var opencodeKnowledge = async () => {
               messageID: input.messageID || ""
             });
           }
-          if (state.role) {
-            const personality = await loadPersonality(state.role);
-            output.parts.push({
-              type: "text",
-              text: `## Role Context
+          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-next.1",
+  "version": "0.4.2",
   "description": "An OpenCode plugin",
   "author": {
     "name": "msegoviadev",