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|

<sub>Calculated with 15k tokens/query (RAG), 300 tokens/query (Pointer), 2.5k tokens/query (Smart Fetch)</sub>

💡 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 💵 |

Read the full Impact Report here

🏗️ 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/KRONOS with 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.py to 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 Oracle module 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):

┌──────────────────────────┬───────────────────────────────

Kronos

Install / Use

README