From 77825a07ea7bf315da2f08ba619b36db5bc9f1fa Mon Sep 17 00:00:00 2001 From: CodingInCarhartts Date: Sun, 14 Dec 2025 12:36:49 -0800 Subject: [PATCH] feat: enhance README with badges, better docs, and fix data paths for npx - Add centered header with npm/license/opencode badges - Add configuration section documenting data location - Add technology stack section - Fix data paths to use ~/.local/share for npx compatibility - Add OPENCODE_PK_DATA_DIR env var for custom data location - Update author in package.json --- README.md | 141 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index b7f2565..2ec5c1a 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,31 @@ -# opencode-personal-knowledge +

+

🧠 opencode-personal-knowledge

+

+ A personal knowledge MCP server with vector database for the Opencode ecosystem +

+

+ npm version + License: MIT + Opencode Compatible +

+

-Personal knowledge MCP server with vector database for the Opencode ecosystem. +--- -## Features +Store and retrieve knowledge using semantic search, powered by local embeddings. No external API keys required. -- **Semantic Search** — Find knowledge using vector embeddings -- **Text Search** — Keyword-based search fallback -- **Tag Organization** — Categorize entries with tags -- **Plug-and-Play** — No external services required (embeddings run locally) +## ✨ Features -## Quick Start (Source installation - Testing) +- **🔍 Semantic Search** — Find knowledge using vector embeddings (all-MiniLM-L6-v2) +- **📝 Text Search** — Keyword-based search fallback +- **🏷️ Tag Organization** — Categorize entries with tags +- **🔌 Plug-and-Play** — No external services required (embeddings run 100% locally) +- **💾 Persistent Storage** — Data stored in `~/.local/share/opencode-personal-knowledge/` +- **🔄 Automatic Indexing** — Entries are vectorized on creation -```bash -# Install dependencies -bun install +## 🚀 Quick Start -# Run CLI -bun start add "Title" "Content" --tags "ai,mcp" -bun start search "query" - -# Run MCP server - For Testing (Not Required for Opencode Integration will auto start on opencode load) -bun run mcp -``` - -## Opencode Integration (Recommended) +### Opencode Integration (Recommended) Add to `~/.config/opencode/opencode.jsonc`: @@ -39,53 +41,92 @@ Add to `~/.config/opencode/opencode.jsonc`: } ``` -## MCP Tools +Restart Opencode — the MCP tools will be available immediately. -| Tool | Description | -| :---------------------- | :-------------------------- | -| `store_knowledge` | Store a new knowledge entry | -| `search_knowledge` | Semantic search | -| `search_knowledge_text` | Keyword search | -| `get_knowledge` | Get entry by ID | -| `update_knowledge` | Update entry | -| `delete_knowledge` | Delete entry | -| `list_knowledge` | List entries | -| `get_knowledge_stats` | Database stats | +### Source Installation (Development) -## Example Usage +```bash +git clone https://github.com/NocturnLabs/opencode-personal-knowledge.git +cd opencode-personal-knowledge +bun install +bun run mcp # Start MCP server +``` + +## 🛠️ MCP Tools + +| Tool | Description | +| :---------------------- | :--------------------------------------------- | +| `store_knowledge` | Store a new knowledge entry with optional tags | +| `search_knowledge` | Semantic similarity search | +| `search_knowledge_text` | Keyword-based text search | +| `get_knowledge` | Retrieve entry by ID | +| `update_knowledge` | Update an existing entry | +| `delete_knowledge` | Delete an entry | +| `list_knowledge` | List entries with filters | +| `get_knowledge_stats` | Database statistics | + +## 📖 Example Usage + +### Storing Knowledge **User:** "store a knowledge entry about Opencode Features" -**Agent:** Researches and compiles entry, then calls `store_knowledge`: +**Agent:** Researches and stores entry: ``` -Tool: personal-knowledge_store_knowledge -Title: "Opencode Features" -Content: "Opencode is an open source AI coding agent that helps write code -in terminals, IDEs, or desktops. Key features include: LSP-enabled, -multi-session support, shareable session links, Claude Pro integration, -75+ LLM providers via Models.dev, and availability across terminal, -desktop app, and IDE extensions." -Tags: ["opencode", "features", "ai-coding-agent"] +✅ Stored knowledge entry #2: "Opencode Features" +📊 Indexed for semantic search ``` -**Result:** `✅ Stored knowledge entry #2: "Opencode Features" 📊 Indexed for semantic search` - ---- +### Searching Knowledge **User:** "@search_knowledge for opencode" -**Agent:** Performs semantic search and returns matching entry: +**Agent:** Returns semantic matches: ``` Found 1 similar entry: ### 1. Opencode Features (85% similar) -Opencode is an open source AI coding agent that helps write code in -terminals, IDEs, or desktops. Key features include: LSP-enabled, -multi-session support, shareable session links, Claude Pro integration... +Opencode is an open source AI coding agent... ``` -## License +## ⚙️ Configuration -MIT +### Data Location + +By default, data is stored in: + +``` +~/.local/share/opencode-personal-knowledge/ +├── knowledge.db # SQLite database +└── vectors/ # LanceDB vector store +``` + +Override with environment variable: + +```bash +export OPENCODE_PK_DATA_DIR=/custom/path +``` + +### Embedding Model + +Uses `Xenova/all-MiniLM-L6-v2` (~22MB, auto-downloads on first use). + +## 🏗️ Technology Stack + +- **Runtime:** [Bun](https://bun.sh) / Node.js +- **Vector DB:** [LanceDB](https://lancedb.com) (embedded) +- **Embeddings:** [Transformers.js](https://huggingface.co/docs/transformers.js) +- **MCP SDK:** [@modelcontextprotocol/sdk](https://modelcontextprotocol.io) +- **Database:** SQLite (via Bun) + +## 📄 License + +MIT © [NocturnLabs](https://github.com/NocturnLabs) + +--- + +

+ Made with ❤️ for the Opencode ecosystem +