Kronos
Connects your code into an intelligent network for perfect context.
Installation
npx kronosAsk AI about Kronos
Powered by Claude Β· Grounded in docs
I know everything about Kronos. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Kronos β³
Local Semantic Memory System for AI Agents
Kronos is an advanced memory system that provides AI agents with long-term memory and deep project context understanding while drastically reducing costs through an innovative "Pointer-based" RAG approach.
π Project Origin & Language Note
Kronos started as a personal internal tool for managing local AI knowledge, primarily documented in Croatian. After seeing its massive impact on development efficiency and ROI, I decided to open-source it to the global community.
We are currently in the process of transitioning all codebase comments and internal documentation to English. If you encounter sections in Croatian, feel free to contribute by providing translations!
π° Token Efficiency - The Kronos Advantage
Why are "Pointers" important?
Traditional RAG systems send entire document blocks to your LLM, consuming huge amounts of tokens. Kronos instead sends lightweight pointers, allowing the AI to decide what it actually needs.
Visual Comparison
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Traditional RAG (Sends all content) β
β ββββββββββββββββββββββββββββββββββββββββββββ 15,000 tokens β
β Cost: $0.021 per query β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Kronos Pointers (Metadata only) β
β ββ 300 tokens β
β Cost: $0.00042 per query β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Kronos Smart Fetch (Pointers + Selective Content) β
β ββββββββ 2,500 tokens β
β Cost: $0.0035 per query β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π **83-98% reduction in token count**
π΅ **5-50x cost savings**
Real-world Cost Calculation
Based on Gemini 1.5 Flash-8B pricing ($0.10/1M input tokens):
| Monthly Volume | Traditional RAG | Kronos (Pointers only) | Kronos (Smart Fetch) | Annual Savings |
|---|---|---|---|---|
| 1,000 queries | $15.00 | $0.30 | $2.50 | $150-176 |
| 10,000 queries | $150.00 | $3.00 | $25.00 | $1,500-1,764 |
| 100,000 queries | $1,500.00 | $30.00 | $250.00 | $15,000-17,640 |
Calculated with 15k tokens/query (RAG), 300 tokens/query (Pointer), 2.5k tokens/query (Smart Fetch)
π‘ Break-even point: ~500 queries (Kronos pays for itself in days, not months!)
β¨ Key Features (v0.6.1)
- π Disk-Based Knowledge Graph: SQLite-powered graph storage for low-RAM usage with Hybrid Rust/Python optimization.
- π Smart Router Arhitektura: Inteligentno prebacivanje izmeΔu Python i Rust motora ovisno o teΕΎini upita.
- β‘ Rust Fast-Path & Traversal (v0.6.2): Ultra-brza pretraga i graf traverzala u Rustu s Recursive CTE optimizacijom (< 1ms za entitete).
- π‘οΈ MCP IDE Integration: Native stdio/SSE communication for Windows agents. Includes "Zero-Pollution" stdout shielding for maximum stability.
- π Shadow Accounting: Built-in tracking of actual token and money savings reported in every AI response.
- π Hybrid Search: Combination of Vector search (ChromaDB) and precise FTS5 keyword search (SQLite).
- βοΈ Temporal Truth: Tracks decision evolution over time (
valid_from,valid_to). - π Project Awareness: Automatic knowledge isolation and filtering per project.
- π οΈ Smart Fetching: AI independently requests exact code lines only when needed.
ποΈ Kronos Architect Protocol
Kronos isn't just a tool; it's a methodology. The Kronos Architect Protocol is a standardized workflow for AI agents that ensures every line of code is built upon existing knowledge, maximizing reuse and minimizing token waste.
- STOP & THINK: Analyze before coding.
- SEARCH: Find existing patterns.
- QUERY: Understand the details.
- REUSE: Adapt, don't invent.
- SYNTHESIS: Execute with precision.
See AGENTS.md and docs/skills/SuperpowersDocs.md for the full protocol definition.
π Case Study: Reducing Hallucinations by 100%
In a real-world scenario (MatematikaPro project), Kronos prevented a "Senior-level" architectural error:
- The Problem: A standard AI agent hallucinated a missing component name (
TikuMessage). - The Solution: Kronos semantically mapped the requirement to the actual file (
TikuBubble.tsx) using its Knowledge Graph. - The Result: 97.8% Token Savings and a surgical fix in under 30 seconds.
| Metric | Without Kronos | With Kronos | Savings |
|---|---|---|---|
| Input Tokens | ~145,000 | ~3,200 | 97.8% π |
| Cost (Est.) | ~$1.50 | ~$0.03 | 50x Cheaper π΅ |
ποΈ High-Level Architecture
[ AI Client / Antigravity ] <--> [ FastAPI Server (Port 8765) ]
|
βββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ
βΌ βΌ βΌ
[ Rust FastPath ] [ SQLite (FTS5) ] [ ChromaDB (Vector) ]
(Literal Matches) (Keyword Rank) (Semantic Score)
β β β
ββββββββββββββββββββββββββββ¬βββββββ΄βββββββββββββββββββββββββββββββ
βΌ
[ Disk Knowledge Graph (v0.6.1) ]
β
[ Oracle (Reranking & Selection) ]
β
[ Context Budgeter ]
π IDE Integration (MCP)
Kronos supports the Model Context Protocol. Configure your IDE (e.g., Gemini/Antigravity) by adding this to your mcp_config.json:
{
"mcpServers": {
"kronos": {
"command": "python",
"args": ["-u", "C:/PATH/TO/KRONOS/src/mcp_server.py"],
"env": {
"PYTHONPATH": "C:/PATH/TO/KRONOS",
"PYTHONUNBUFFERED": "1"
}
}
}
}
Note: Replace
C:/PATH/TO/KRONOSwith the actual absolute path to your cloned Kronos directory.
π‘οΈ Windows Robustness
The server uses OS-level stdout hijacking (os.dup2) to prevent communication "pollution". All non-JSON output (logs, native noise) is redirected to stderr.
π Quick Start Guide
1. Prerequisites
- Python 3.10+ needed.
- Windows Users: You might need Visual Studio C++ Build Tools for
chromadb.
2. Installation & Setup
A. Automated Setup (Recommended for Windows)
Just run the setup script. It will create a virtual environment, install dependencies, and walk you through the language configuration (English/Croatian).
./setup.ps1
B. Manual Installation
If you prefer manual control:
# 1. Clone repository & enter
git clone https://github.com/Ja1Denis/Kronos.git
cd Kronos
# 2. Create and activate Virtual Environment
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
source venv/bin/activate # Mac/Linux
# 3. Install Dependencies
pip install -r requirements.txt
# 4. Configure Language (i18n)
python configure.py
π Verification: Run
python scripts/check_env.pyto verify everything is installed correctly.
3. API Configuration π
Create a .env file in the root directory (automatically created if you used setup.ps1) and add your API key:
OPENROUTER_API_KEY=your_key_here
KRONOS_LANG=en # Or 'hr' for Croatian
3. Build Knowledge Graph (First Run)
Initialize the project memory:
python scripts/build_knowledge_graph.py --path . --project MyProject
4. Ingestion
Ingest your codebase into the vector database:
python .\ingest_everything.py
5. IDE Integration (MCP)
Add Kronos to your MCP client configuration (e.g., mcp_config.json for Antigravity or Claude Desktop).
Critical: Point to the python executable inside your venv!
{
"mcpServers": {
"kronos": {
"command": "C:/PATH/TO/Kronos/venv/Scripts/python.exe",
"args": ["-u", "C:/PATH/TO/Kronos/src/mcp_server.py"],
"env": {
"PYTHONPATH": "C:/PATH/TO/Kronos",
"PYTHONUNBUFFERED": "1"
}
}
}
}
6. Usage (AI Agents)
Once the server is running (via MCP in your IDE), you can simply mention @kronos in your prompt.
Example:
"@kronos How does the
Oraclemodule handle context ranking?"
Kronos will intercept the request, search its memory, and inject the relevant code/docs into the context before the LLM answers.
7. Monitoring & Efficiency π
Track your knowledge growth and financial savings at any time:
A. Via Terminal (CLI)
python -m src.main stats
B. Via AI Agent (MCP)
If you are using an MCP-compatible IDE (like Cursor or Antigravity), you can simply ask the LLM:
"@kronos show me
kronos_stats"
Example Output (Power User):
ββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ
β Category β Details β
ββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββ€
β Total Files β 12,450 β
β Total Chunks β 158,200 β
β Extracted Knowledge β β’ Code: 45,600 β
β β β’ Decision: 842 β
β β β’ Problem: 312 β
β β β’ Solution: 295 β
β β β’ Task: 8,400 β
β Database Size β 4.82 GB β
β Job Queue β Total: 12,500 | OK: 99.9% | Lat: 0.8s β
β Saved Tokens (30d) β 12,450,000 β
β Avoided Cost (30d) β $124.50 β
β Total Savings (All-time) β $1,450.25 β
ββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββ
β Troubleshooting
MCP Error: "EOF" or "Connection Closed" (cortex_step_type_mcp_tool)
- Symptom: Your IDE (like Gemini CLI or Cursor) reports an EOF error and closes the connection as soon as you try to run any tool (like
kronos_query). - Cause: The IDE is silently crashing because it is trying to run Kronos with the global, system-wide
pythoninstead of your virtual environment. The global Python likely lacks critical dependencies (e.g.,chromadb), crashing the server immediately before it can report a meaningful error. - Fix: In your
mcp_config.json(or IDE settings), change the"command": "python"line to use the absolute path of your venv python."command": "C:/absolute/path/to/Kronos/venv/Scripts/python.exe"
"No module named 'FastMCP'"
- Cause: Missing
mcppackage or using an old version. - Fix: Run
pip install -r requirements.txtand ensuremcp>=1.0.0is installed. Note:FastMCPis part of themcppackage, not a separatepip install fastmcp.
"SQLite version too old" (chromadb error)
- Cause: Windows often has an old generic SQLite DLL.
- Fix: Install
pysqlite3-binaryand overridesqlite3in your code, or simply downloadsqlite3.dllfrom sqlite.org and place it in your Python DLLs folder (or strictly use the venv provided one if it's newer).
π οΈ Development & Maintenance
Reset and Wipe
For a fresh start:
# Force wipe without confirmation
.\run.ps1 wipe --force
Testing
python -m pytest tests/ -v
π License & Credits
Made with β€οΈ for advanced AI collaboration by Denis SakaΔ. Licensed under the MIT License.
