mirror of
https://github.com/NocturnLabs/opencode-personal-knowledge.git
synced 2026-07-18 08:05:59 +02:00
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
This commit is contained in:
CodingInCarhartts
@@ -1,29 +1,31 @@
|
||||
# opencode-personal-knowledge
|
||||
<p align="center">
|
||||
<h1 align="center">🧠 opencode-personal-knowledge</h1>
|
||||
<p align="center">
|
||||
<strong>A personal knowledge MCP server with vector database for the Opencode ecosystem</strong>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://www.npmjs.com/package/opencode-personal-knowledge"><img src="https://img.shields.io/npm/v/opencode-personal-knowledge.svg" alt="npm version"></a>
|
||||
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
||||
<a href="https://opencode.ai"><img src="https://img.shields.io/badge/Opencode-Compatible-blue.svg" alt="Opencode Compatible"></a>
|
||||
</p>
|
||||
</p>
|
||||
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
Made with ❤️ for the <a href="https://opencode.ai">Opencode</a> ecosystem
|
||||
</p>
|
||||
|
||||
Reference in New Issue
Block a user