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.9.8-alpha)

• 🧠 OpenRouter Embeddings (text-embedding-3-large): Puna semantička neovisnost o Google API-ju uz nativnu dimenziju 3072 kompatibilnu s postojećom bazom znanja.
• ⚡ Jev AI "System One" Decision Engine: Ultra-brzo (~100ms) i ekstremno jeftino ($0.042/1M tokena) determinističko odlučivanje, usmjeravanje i evaluacija putem OpenRouter Decisions API-ja.
• 🤖 Samostalni MCP Decision Alat (kronos_jev_decide): Omogućuje vanjskim agentima (Hermes, Claude Desktop, Antigravity) da u hodu donose strukturirane odluke s vjerojatnostima.
• 🎯 score tip pitanja (NOVO v0.9.8): kronos_jev_decide sada podržava ocjenu na skali 2–10 razina (score_levels). Score je vjerojatnosno težište i može pasti između razina; odgovor sadrži legend i probabilities. Primjena: ranking leadova, ocjena kvalitete teksta, severity grading.
• 🔀 Fan-out mod (NOVO v0.9.8): questions parametar prima dict više pitanja različitih tipova (choice/noul/score) u JEDNOM pozivu — npr. QA gate s 5 provjera teksta u jednom Jev pozivu umjesto pet odvojenih. Uključena validacija tipova prije slanja. Stari pozivi (choice/noul) rade neizmijenjeno.
• 🧠 Smart Context Engine: Otkrivanje, semantičko podudaranje i human-in-the-loop odobrenje skillova s Adaptive RAG (Odlučivačem).
• 🚦 Adaptive RAG Routing: Automatska klasifikacija upita u tri razine (SIMPLE, MODERATE, COMPLEX) i optimizirano usmjeravanje resursa.
• 🧹 CRAG Evaluator: Heuristički i Jev AI "filter šuma" (Corrective RAG) koji ocjenjuje kvalitetu dohvata i odbacuje nerelevantne isječke koda prije nego dođu do LLM-a.
• 🗜️ Context Compression: Rule-based sažimanje koje uklanja prazne linije, komentare i docstringove iz koda, štedeći dragocjene tokene bez gubitka logike.
• ⚡ Semantic Cache: SQLite cache s definiranim TTL-om, značajno ubrzava ponovljene semantičke upite (hit-rate > 80% na sličnim pitanjima).
• 🕸️ Graph RAG: Integracija skillova i entiteta u graf, omogućavajući "multi-hop" traverzale za složene arhitektonske upite.
• 🔌 MCP Tool Routing: Tri specijalizirana alata (kronos_ping, kronos_reinit_oracle, kronos_query) dizajnirana za optimalnu suradnju s Antigravity agentima.
• 📊 Disk-Based Knowledge Graph: SQLite-powered graph storage za nisku potrošnju RAM-a uz Hybrid Rust/Python optimizaciju.
• 🚀 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 komunikacija uz "Zero-Pollution" stdout zaštitu.
• 📉 Shadow Accounting: Ugrađeno praćenje uštede tokena i novca, prijavljeno u svakom AI odgovoru.
• 🔄 Self-RAG Loop: Evaluira dostatnost konteksta pomoću LLM-a i dinamički proširuje upite ako nedostaju detalji.

📐 Arhitektura v0.9.5 (Jev AI Fast Decision, Adaptive RAG & Compression)

┌─────────────────┐       ┌────────────────────────┐
│  Korisnički upit │ ────▶ │ Odlučivač (Jev AI ~100ms)│ ──▶ [ SIMPLE ] ──▶ FTS5 / Vector Cache
└─────────────────┘       └──────────┬─────────────┘
                                     │
                             [ MODERATE / COMPLEX ]
                                     ▼
                          ┌──────────────────────┐
                          │   Graph Traversal    │ (Multi-hop pretraga)
                          └──────────┬───────────┘
                                     ▼
                          ┌──────────────────────┐
                          │    CRAG Evaluator    │ (Odbacivanje nevažnih isječaka)
                          └──────────┬───────────┘
                                     ▼
                          ┌──────────────────────┐
                          │ Context Compression  │ (Uklanjanje šuma iz koda)
                          └──────────┬───────────┘
                                     ▼
                          ┌──────────────────────┐
                          │   Smart Fetching     │ ──▶ Odgovor AI-u
                          └──────────────────────┘

---

🏛️ 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.

1. STOP & THINK: Analyze before coding.
2. SEARCH: Find existing patterns.
3. QUERY: Understand the details.
4. REUSE: Adapt, don't invent.
5. 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

---

📊 Benchmark: Self-RAG vs Standard RAG

We measure the reliability and latency trade-offs of the Self-RAG loop against traditional single-turn RAG retrieval:

Query Type / Scenario	Standard RAG Latency	Self-RAG Latency	Retrieval Loops	Context Quality & Completeness
Simple Query(Sufficient initial context)	~812 ms	~814 ms	1x	100% Complete(Evaluator accepts context immediately)
Complex Query(Missing code specifications)	~845 ms	~1,675 ms	2x	100% Complete 🚀(Standard RAG is incomplete, Self-RAG auto-requeries)

💡 Key Insight: Self-RAG introduces a negligible ~2ms (0.2%) overhead for simple queries where context is sufficient. For complex queries with missing code specifications, it dynamically runs a secondary re-query (loops=2x). While this increases latency, it guarantees 100% context completeness, preventing the AI from hallucinating or failing.

---

🏗️ High-Level Architecture

[ AI Client / Antigravity ] <--> [ FastAPI Server (Port 8765) ]
                                          |
        ┌─────────────────────────────────┴──────────────────────────────┐
        ▼                                 ▼                              ▼
 [ Rust FastPath ]                [ SQLite (FTS5) ]            [ SQLite (sqlite-vec) ]
 (Literal Matches)                (Keyword Rank)               (Semantic Match SQL)
        │                                 │                              │
        └──────────────────────────┬──────┴──────────────────────────────┘
                                   ▼
                    [ Disk Knowledge Graph (v0.7.3) ]
                                   │
                   [ Oracle (Reranking & Selection) ]
                                   │
                          [ Context Budgeter ]

---

⚖️ Temporal Knowledge Graph & Soft-Delete

To prevent AI context pollution, Kronos v0.7.3 introduces a Temporal Knowledge Graph. When files are modified or deleted in your codebase, traditional memory graphs get cluttered with obsolete code elements and outdated relationship definitions.

Kronos solves this by tracking the time-domain validity of every node (e.g. classes, functions, files) and edge (e.g. CONTAINS, HAS_METHOD, IMPORTS):

• No Hard Deletes: Old entities are never deleted physically. Instead, their valid_to timestamp is set to the current time, rendering them inactive.
• Active Filter: AI retrieval tools (such as BFS traversal, neighbor queries, and Recursive CTE paths in Python and Rust) automatically query only currently valid objects (valid_to IS NULL).
• Evolution Tracking: When a class is modified (e.g. changing its docstring or adding a method), the database keeps the old version (with valid_to set to now) and inserts a new active version (with valid_to = None). This allows the memory system to maintain a complete history of the codebase evolution over time.

---

🚀 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.
• Zero-Compile Setup: No Microsoft Visual C++ Build Tools required! sqlite-vec runs natively out of the box.

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.

6.1 Jev Decision Tool (kronos_jev_decide)

Ultra-fast System-1 decision maker (~0.3–1 s, fractions of a cent per call) available to any MCP-connected agent.

Single decision — choice (pick one option), noul (yes/no probability), score (grade on a scale, v0.9.8+):

kronos_jev_decide(
  instructions="Grade this sales pitch quality (0=worst, 4=best)",
  question_type="score",
  score_levels=["unusable", "average", "good", "very good", "top-notch"],
  state={"pitch": "..."}
)
# → {"status": "success", "question_type": "score", "score": 2.03,
#    "legend": {"0": "unusable", ..., "4": "top-notch"},
#    "probabilities": {...}, "confidence": 0.66}

Fan-out — many questions in ONE call (v0.9.8+):

kronos_jev_decide(
  instructions="ignored in fan-out mode",
  state={"pitch": "..."},
  questions={
    "has_price":  {"type": "noul",  "instructions": "Does the pitch mention a price?",
                   "criteria": {"true": "contains a number with currency", "false": "no price"}},
    "ends_ok":    {"type": "noul",  "instructions": "Does it end with the exact closing question?",
                   "criteria": {"true": "yes", "false": "no"}},
    "quality":    {"type": "score", "instructions": "Overall pitch quality",
                   "criteria": ["unusable", "average", "good", "very good", "top-notch"]}
  }
)
# → {"status": "success", "question_type": "fan_out",
#    "answers": {"has_price": {"noul": 0.03}, "ends_ok": {"noul": 0.92},
#                "quality": {"score": 2.31, ...}}, "latency_ms": 614}

When to use it: bounded judgment calls (gates, classification, routing, grading) where a regex keeps breaking and a full LLM call is overkill. Not for: arithmetic, date math, anything requiring the model to read files or remember context — numbers and thresholds stay in your code.

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 python instead 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 mcp package or using an old version.
• Fix: Run pip install -r requirements.txt and ensure mcp>=1.0.0 is installed. Note: FastMCP is part of the mcp package, not a separate pip install fastmcp.

"SQLite version too old" (chromadb error)

• Cause: Windows often has an old generic SQLite DLL.
• Fix: Install pysqlite3-binary and override sqlite3 in your code, or simply download sqlite3.dll from 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.