kave

README

کاوه / Kave

The Blacksmith’s Extended Intelligence

Kave (named after Kaveh the Blacksmith) is a local-first, privacy-native second brain for developers. It is not just an AI assistant; it is a background infrastructure that sits between your OS and your LLM to provide a persistent, real-time memory of everything you do, build, and think.

"Kaveh forged his own tools to rise against tyranny. We forge our own models to reclaim our context."

---

🧠 The Core Vision: "Zero Prompt Length"

The goal of Kave is to eliminate the need for copy-pasting code or explaining context. By the time you ask a question, Kave already knows your recent terminal errors, the file you just saved, and your personal architectural preferences.

🛡️ Key Pillars

• The Passive Forge (Real-Time Ingestion): * Hot-Embedding: Kave watches your projects. Hit save in your editor, and the code is re-embedded into your local vector space instantly.

• System Pulse: Automatically ingests shell history, git commits, and file changes. It learns from your process, not just your results.

• The Contextual Spark (Smart Retrieval): * Weighted Reconstructon: Retrieval isn't just a search; it’s a sliding window that balances Recency (what just happened), Relevancy (past similar bugs), and Persona (how you want the answer delivered).

• Location Awareness: Kave knows if you're in a /tests folder or a /cmd folder and adjusts its logic accordingly.

• Persona-Driven Intelligence:

• Switch between "The Performance Architect," "The Security Auditor," or "The Bilingual Educator" (Persian/English). Each persona filters and interprets your memories differently.

• Tooling for Tools: * Designed to act as a high-context backend for agents like Claude Code, delegating specialized tasks to local models (Ollama).

---

🛠️ Stack & Architecture

• Go 1.26 + Fiber v3: High-performance agent runtime and API.
• PostgreSQL 18.3 + pgvector: The permanent "cerebral cortex" for storage and semantic search.
• Ollama: The local "engine" for LLM inference (Qwen, DeepSeek, Mistral).
• HTMX + Svelte: A minimalist "Memory Lab" web UI for visualizing your knowledge graph.
• System Service: Runs as a background utility (via systemd or similar) in ~/.config/kave.

---

⌨️ Usage

The CLI

Kave is designed to be lived in via the terminal.

# Initialize Kave and start the background forge
kave start

# Tell Kave to watch and ingest a specific project in real-time
cd ~/projects/neural-lab
kave init

# Ask a question using the 'blacksmith' persona
kave ask "Why did my last git commit fail the build?" --persona blacksmith

The Web UI (The Lab)

Access your "Knowledge Graph" and "Persona Forge" at http://localhost:8080.

• Timeline: See a visual history of your system's activity.
• Pruning: Delete "bad memories" or outdated code snippets to keep context clean.

---

🚀 Status: 🔨 Actively Forging

Kave is currently in its early development phase. The core database schema and project structure are settled. We are now focusing on:

1. High-speed file watching for real-time re-embedding.
2. Sliding-window retrieval algorithms.
3. Bilingual context mapping for Persian-speaking developers.

---

📋 Setup

Kave is local-only. No data leaves your machine. Ever. See docs/setup.md for installation instructions on CachyOS, Linux, or MacOS.

---

Author

👤 Ali Julaee Rad

• GitHub: alijeyrad
• LinkedIn: in/ali-julaee-rad
• Email: alijrad.dev@gmail.com

License

This project is open source see the LICENSE file for more details. Contributions are welcome.