opencode-knowledge 0.3.4 → 0.4.0-next.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 zenobi.us
+Copyright (c) 2026 msegoviadev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,87 +1,438 @@
 # opencode-knowledge
 
-An OpenCode plugin
-
-> An OpenCode plugin created from the [opencode-plugin-template](https://github.com/zenobi-us/opencode-plugin-template)
+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
 
-- 🏗️ TypeScript-based plugin architecture
-- 🔧 Mise task runner integration
-- 📦 Bun/npm build tooling
-- ✨ ESLint + Prettier formatting
-- 🧪 Vitest testing setup
-- 🚀 GitHub Actions CI/CD
-- 📝 Release automation with release-please
+### 🎭 Personality System
+Choose from different AI personas (staff engineer, frontend specialist, cthulhu, etc.) that influence how OpenCode communicates and approaches problems.
 
-## Getting Started
+### 📚 Knowledge Vault
+Create a structured library of markdown-based knowledge packages with frontmatter metadata for easy discovery and loading.
 
-1. **Clone this template:**
+### 🔍 Smart Search
+Tag-based search system finds relevant knowledge packages based on your current task.
 
-   ```bash
-   cp -r opencode-plugin-template your-plugin-name
-   cd your-plugin-name
-   ```
+### 💾 Session Persistence
+Tracks loaded packages across sessions and provides token-optimized context injection.
 
-2. **Update package.json:**
-   - Change `name` to your plugin name
-   - Update `description`
-   - Update `repository.url`
+---
 
-3. **Install dependencies:**
+## Installation
 
-   ```bash
-   bun install
-   ```
+Add the plugin to your OpenCode config:
 
-4. **Implement your plugin in `src/index.ts`:**
+**Global config** (`~/.config/opencode/opencode.json` or `opencode.jsonc`):
 
-   ```typescript
-   import type { Plugin } from '@opencode-ai/plugin';
+```json
+{
+  "plugin": ["opencode-knowledge"]
+}
+```
 
-   export const YourPlugin: Plugin = async (ctx) => {
-     return {
-       tool: {
-         // Your plugin tools here
-       },
-     };
-   };
-   ```
+**Or per-project** (`opencode.json` or `opencode.jsonc` in your project root):
 
-5. **Test your plugin:**
-   ```bash
-   mise run test
-   ```
+```json
+{
+  "plugin": ["opencode-knowledge"]
+}
+```
 
-## Development
+---
 
-- `mise run build` - Build the plugin
-- `mise run test` - Run tests
-- `mise run lint` - Lint code
-- `mise run lint:fix` - Fix linting issues
-- `mise run format` - Format code with Prettier
+## Quick Start
 
-## Installation in OpenCode
+### 1. Create Settings File
 
-Create or edit `~/.config/opencode/config.json`:
+Create `.opencode/knowledge/settings.json` in your project:
 
 ```json
 {
-  "plugins": ["opencode-knowledge"]
+  "role": "staff_engineer"
 }
 ```
 
-## Author
+### 2. Create Knowledge Vault (Optional)
+
+If you want to use the knowledge management features, create a vault structure:
+
+```bash
+mkdir -p .opencode/knowledge/vault/standards
+```
+
+### 3. Create Your First Knowledge Package
+
+Create `.opencode/knowledge/vault/standards/code-conventions.md`:
+
+```markdown
+---
+tags:
+  - standards
+  - typescript
+  - conventions
+description: Core code conventions and style guide
+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
+
+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
+
+Search for packages by tags:
+
+```
+knowledge_search [tags=typescript,conventions]
+```
+
+Load packages into your session:
+
+```
+knowledge_load [paths=standards/code-conventions.md]
+```
+
+---
+
+## Available Personalities
+
+### staff_engineer
+
+Skeptical, pragmatic Staff Engineer focused on architecture, coupling, operational risk, and maintainability.
+
+**Best for**: Code reviews, architecture decisions, production systems
+
+### cthulhu
+
+Ancient cosmic entity providing technical guidance with existential dread and cosmic perspective.
+
+**Best for**: When you need technical help but also want to contemplate the meaninglessness of time
+
+---
+
+## 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
 
-msegoviadev <marcos@msegovia.dev>
+Knowledge packages are markdown files with YAML frontmatter:
 
-## Repository
+```markdown
+---
+tags:
+  - tag1
+  - tag2
+  - tag3
+description: Brief description of this package
+category: category-name
+required_knowledge:
+  - other-package-1
+  - other-package-2
+file_patterns:
+  - "*.tsx"
+  - "*.test.ts"
+---
 
-https://github.com/msegoviadev/opencode-knowledge
+# Package Title
+
+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 |
+
+---
+
+## Directory Structure
+
+```
+your-project/
+└── .opencode/
+    └── knowledge/
+        ├── settings.json              # Plugin configuration
+        ├── knowledge.json             # Auto-generated catalog (gitignored)
+        ├── vault/                     # Your knowledge packages
+        │   ├── frontend/
+        │   │   ├── react-patterns.md
+        │   │   └── state-management.md
+        │   ├── backend/
+        │   │   └── api-design.md
+        │   └── standards/
+        │       ├── code-conventions.md
+        │       └── testing-guide.md
+        └── 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
+
+```bash
+mise run build
+```
+
+Or directly with Bun:
+
+```bash
+bun build ./src/index.ts --outdir dist --target bun
+```
+
+### Linting
+
+```bash
+mise run lint       # Check for issues
+mise run lint:fix   # Auto-fix issues
+```
+
+### Formatting
+
+```bash
+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 are welcome! Please file issues or submit pull requests on the GitHub repository.
+Contributions welcome! Please:
+
+1. Follow the code conventions in `AGENTS.md`
+2. Run `mise run lint` before committing
+3. Update documentation for new features
+4. Add tests for new functionality
+
+---
 
 ## License
 

package/dist/templates/first-prompt.template.md

@@ -9,10 +9,22 @@ You have access to a comprehensive knowledge base containing {{CATEGORIES_COUNT}
 **Packages:** 
 {{CORE_PACKAGES_LIST}}
 
-### Your Task
-{{USER_PROMPT}}
+### Available Knowledge Tools
 
-### Knowledge Loading
-You can load specific knowledge packages using the knowledge_load tool when relevant to the task at hand. Focus on packages that match the technical domain or problem you're solving.
+You have access to the following tools for working with the knowledge vault:
 
-Available knowledge packages can be discovered by searching for specific tags, technologies, or domains using the knowledge_search tool.
+**knowledge_search** - Search for packages by tags
+- Use this to discover relevant knowledge packages
+- Provide comma-separated tags (e.g., "typescript,react,testing")
+- Returns ranked list of matching packages with relevance scores
+
+**knowledge_load** - Load packages into context
+- Use this to inject knowledge package content into the session
+- Provide comma-separated paths (e.g., "standards/code-conventions.md")
+- Returns package content and metadata for your reference
+
+**knowledge_index** - Rebuild catalog (rarely needed)
+- Use this if search results seem outdated or after adding packages
+- Automatically runs on session start
+
+Use these tools proactively when you need domain-specific guidance or best practices.

package/package.json

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

package/dist/index.js

@@ -1,221 +0,0 @@
-// @bun
-// src/index.ts
-import path from "path";
-import { fileURLToPath } from "url";
-import { readFile as readFile2 } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-
-// src/lib/session-state.ts
-import { readFile } from "fs/promises";
-import { existsSync } from "fs";
-var sessionStates = new Map;
-async function createSessionState(sessionId) {
-  if (sessionStates.has(sessionId)) {
-    throw new Error(`Session state already exists for session: ${sessionId}`);
-  }
-  const settingsPath = ".opencode/knowledge/settings.json";
-  if (!existsSync(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,
-    isFirstPrompt: true,
-    loadedPackages: new Set,
-    createdAt: new Date
-  };
-  sessionStates.set(sessionId, state);
-}
-function getSessionState(sessionId) {
-  const state = sessionStates.get(sessionId);
-  if (!state) {
-    throw new Error(`Session state not found for session: ${sessionId}`);
-  }
-  return state;
-}
-function updateSessionState(sessionId, updates) {
-  const state = getSessionState(sessionId);
-  Object.assign(state, updates);
-}
-
-// src/index.ts
-var logToFile = async (message) => {
-  try {
-    const logEntry = `${new Date().toISOString()}: ${message}
-`;
-    let existing = "";
-    try {
-      existing = await Bun.file("/tmp/opencode-knowledge-debug.log").text();
-    } catch {}
-    await Bun.write("/tmp/opencode-knowledge-debug.log", existing + logEntry);
-  } catch (e) {}
-};
-function parseFrontmatter(content) {
-  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-  if (!match) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-  const [, yamlContent, body] = match;
-  const frontmatter = {};
-  for (const line of yamlContent.split(`
-`)) {
-    const colonIndex = line.indexOf(":");
-    if (colonIndex === -1)
-      continue;
-    const key = line.slice(0, colonIndex).trim();
-    const value = line.slice(colonIndex + 1).trim();
-    if (key === "description")
-      frontmatter.description = value;
-    if (key === "agent")
-      frontmatter.agent = value;
-    if (key === "model")
-      frontmatter.model = value;
-    if (key === "subtask")
-      frontmatter.subtask = value === "true";
-  }
-  return { frontmatter, body: body.trim() };
-}
-async function loadCommands() {
-  const commands = [];
-  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
-  const commandDir = path.join(__dirname2, "command");
-  if (!existsSync2(commandDir)) {
-    return commands;
-  }
-  const glob = new Bun.Glob("**/*.md");
-  for await (const file of glob.scan({ cwd: commandDir, absolute: true })) {
-    const content = await Bun.file(file).text();
-    const { frontmatter, body } = parseFrontmatter(content);
-    const relativePath = path.relative(commandDir, file);
-    const name = relativePath.replace(/\.md$/, "").replace(/\//g, "-");
-    commands.push({
-      name,
-      frontmatter,
-      template: body
-    });
-  }
-  return commands;
-}
-async function loadPersonality() {
-  const settingsPath = ".opencode/knowledge/settings.json";
-  if (!existsSync2(settingsPath)) {
-    const errorMsg = `\u274C CONFIGURATION ERROR: Settings file not found at ${settingsPath}. Please create this file with {"role": "your_role"}`;
-    await logToFile(errorMsg);
-    throw new Error(errorMsg);
-  }
-  let role;
-  try {
-    const settingsContent = await readFile2(settingsPath, "utf-8");
-    const settings = JSON.parse(settingsContent);
-    if (!settings.role) {
-      const errorMsg = `\u274C CONFIGURATION ERROR: Settings file exists but missing 'role' field. Please add {"role": "your_role"} to ${settingsPath}`;
-      await logToFile(errorMsg);
-      throw new Error(errorMsg);
-    }
-    role = settings.role;
-    await logToFile(`\u2705 Settings loaded: role="${role}" from ${settingsPath}`);
-  } catch (error) {
-    if (error instanceof Error && error.message.includes("CONFIGURATION ERROR")) {
-      throw error;
-    }
-    const errorMsg = `\u274C Error parsing settings.json: ${error}`;
-    await logToFile(errorMsg);
-    throw new Error(errorMsg);
-  }
-  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
-  let personalityPath = path.join(__dirname2, "..", "templates", "personalities", `${role}.txt`);
-  if (!existsSync2(personalityPath)) {
-    personalityPath = path.join(__dirname2, "templates", "personalities", `${role}.txt`);
-  }
-  if (!existsSync2(personalityPath)) {
-    const errorMsg = `\u274C CONFIGURATION ERROR: Personality file not found at ${personalityPath}. Available roles should have a corresponding .txt file in templates/personalities/`;
-    await logToFile(errorMsg);
-    throw new Error(errorMsg);
-  }
-  const content = await readFile2(personalityPath, "utf-8");
-  await logToFile(`\u2705 Personality loaded from: ${personalityPath}`);
-  return content.trim();
-}
-var opencodeKnowledge = async (ctx) => {
-  await logToFile("Plugin initialized");
-  const commands = await loadCommands();
-  return {
-    async config(config) {
-      config.command = config.command ?? {};
-      for (const cmd of commands) {
-        let template = cmd.template;
-        template = template.replace("{{CURRENT_TIME}}", new Date().toISOString());
-        config.command[cmd.name] = {
-          template,
-          description: cmd.frontmatter.description,
-          agent: cmd.frontmatter.agent,
-          model: cmd.frontmatter.model,
-          subtask: cmd.frontmatter.subtask
-        };
-      }
-    },
-    "chat.message": async (input, output) => {
-      try {
-        const state = getSessionState(input.sessionID);
-        if (state.isFirstPrompt) {
-          await logToFile(`\uD83C\uDFAF First message in session ${input.sessionID} - injecting personality`);
-          const personality = await loadPersonality();
-          const personalityPart = {
-            type: "text",
-            text: `## Role Context
-
-${personality}`,
-            id: `personality-${Date.now()}`,
-            sessionID: input.sessionID,
-            messageID: input.messageID || ""
-          };
-          output.parts.push(personalityPart);
-          updateSessionState(input.sessionID, { isFirstPrompt: false });
-          await logToFile("\u2705 Personality injected on first message!");
-        } else {
-          await logToFile(`\u23ED\uFE0F  Subsequent message - skipping personality injection`);
-        }
-      } catch (error) {
-        await logToFile(`\u274C Error in chat.message: ${error}`);
-      }
-    },
-    event: async ({ event }) => {
-      try {
-        if (event.type === "session.created") {
-          await logToFile("\uD83D\uDE80 session.created event");
-          const eventData = event;
-          const sessionId = eventData.properties?.info?.id;
-          if (!sessionId) {
-            const errorMsg = `\u274C Could not extract session ID from session.created event`;
-            await logToFile(errorMsg);
-            await logToFile(`Event structure: ${JSON.stringify(eventData)}`);
-            throw new Error(errorMsg);
-          }
-          await logToFile(`\u2705 Extracted session ID: ${sessionId}`);
-          await createSessionState(sessionId);
-          const state = getSessionState(sessionId);
-          await logToFile(`\u2705 Session state created for session ${sessionId} with role: ${state.role}`);
-        }
-      } catch (error) {
-        await logToFile(`\u274C Error in event: ${error}`);
-      }
-    }
-  };
-};
-export {
-  opencodeKnowledge
-};

package/dist/templates/abbreviated.template.md

@@ -1,8 +0,0 @@
-## Knowledge Context
-
-You have access to an engineering knowledge base. Core areas include **{{CORE_TAGS}}** and key packages: **{{CORE_PACKAGES}}**.
-
-### Your Task
-{{USER_PROMPT}}
-
-Use knowledge_load and knowledge_search tools to access relevant information as needed.