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
+
+
+ 
+ 
+ 
+
+
-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
+