kryth 0.1.0

AI Agent Memory Framework — structured memory layers for LLM-based agents

🧠 Kryth

AI Agent Memory Framework — Structured memory layers for LLM-based agents

🚀 Quick Start • ✨ Features • 🏗️ Architecture • 📦 Installation • 🤝 Contributing

---

💡 Why Kryth?

LLM-based agents need memory — but not just any memory. They need structured, token-efficient, deduplicated memory that fits inside a context window. Kryth gives you:

Without Kryth	With Kryth
❌ Bloated, unstructured context	✅ Token-capped retrieval (~800 tokens)
❌ Duplicate reads and redundant commands	✅ Smart duplicate detection & summarization
❌ Runaway memory growth	✅ Automatic compression with configurable limits
❌ Ad-hoc memory management	✅ Clean, modular controller architecture

---

🚀 Quick Start

from kryth import WriteController, RetrievalController, compute_state_hash

# Compute a unique state hash for your project
state_hash = compute_state_hash(cwd="/path/to/project")

# Route knowledge from tool calls into memory
write_ctrl = WriteController()
write_ctrl.on_tool_result(
    tool_name="read_file",
    args={"path": "main.py"},
    result="file contents...",
    error=False,
    session_id=1,
    memory_manager=memory_manager,  # Your MemoryManager instance
    turn=3,
)

# Retrieve only the most relevant memories for LLM context
retrieval_ctrl = RetrievalController()
context_block = retrieval_ctrl.build_prompt_block(
    memory_manager=memory_manager,
    session_id=1,
    user_input="What does the auth module do?",
)

💡 Tip: Kryth is designed to integrate with your existing MemoryManager. See the full documentation for setup details.

---

✨ Features

🧩 Modular Architecture Each memory concern — writing, retrieval, deduplication, compression — is isolated in its own controller. Mix and match what you need.	📏 Token-Aware Retrieval Context injection is always capped at ~800 tokens, ensuring your LLM stays focused and never exceeds context limits.
🎯 Relevance Ranking Memories are scored and ranked by importance × query relevance, so only the most pertinent information makes it into the prompt.	🔍 Smart Duplicate Detection Detects duplicate file reads and command executions — then returns a summary instead of hard-blocking. Never repeat work.
🧹 Automatic Compression Prevents unbounded memory growth with configurable limits per memory layer. Set it and forget it.	🔐 State Hashing Robust duplicate command detection using git diff, file hashes, and environment variables. Know when state has genuinely changed.

---

🏗️ Architecture

Kryth organizes memory into a clean, layered architecture:

flowchart TB
    subgraph Input["📥 Inputs"]
        TC[Tool Calls]
        UI[User Input]
    end

    subgraph Controllers["🎮 Controllers"]
        WC[WriteController]
        RD[DuplicateDetector]
        RC[RetrievalController]
        CC[CompressionController]
    end

    subgraph Memory["💾 Memory Layers"]
        RM[RepoMemory<br/>File contents, symbols]
        EM[ExecutionMemory<br/>Command history]
        EPM[EpisodicMemory<br/>Edits, decisions]
        WM[WorkingMemory<br/>Objective, blockers]
        LTM[LongTermMemory<br/>Summarized insights]
    end

    TC --> WC
    WC --> RM
    WC --> EM
    WC --> EPM
    WC --> WM
    WC --> RD
    RD -.->|Soft dedup| TC

    UI --> RC
    RC --> RM
    RC --> EM
    RC --> EPM
    RC --> WM
    RC -.->|Optional| LTM

    CC --> EPM
    CC --> LTM
    CC --> EM

Memory Layers

Layer	Purpose	Written By
RepoMemory	File contents, structure, symbols	read_file
ExecutionMemory	Command history and results	run_command
EpisodicMemory	Edits, decisions, findings	edit_file, write_file
WorkingMemory	Current objective and blockers	set_objective
LongTermMemory	Summarized insights	Compression

Retrieval Priority

The RetrievalController builds context blocks in strict priority order, ensuring the most critical information is always included:

🥇  Current objective (always included)
🥈  Working memory findings + blockers
🥉  Top repo memory hits (ranked by importance × relevance)
    Recent command execution results
    Critical episodic findings
    Long-term memory summaries (optional)

---

📦 Installation

Stable release (recommended):

pip install kryth

Development version:

git clone https://github.com/navadeep0508/KRYTH-OS.git
cd kryth
pip install -e ".[dev]"

---

🧪 Development

# Set up environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Code quality
ruff check src/
mypy src/

---

🗺️ Roadmap

• Core memory controllers (Write, Retrieve, Deduplicate, Compress)
• Token-capped context retrieval
• Integration with popular agent frameworks (LangChain, CrewAI)
• Persistent storage backends (SQLite, PostgreSQL, Redis)
• Async-first API
• Interactive memory dashboard

---

🤝 Contributing

Contributions are what make the open source community such an amazing place! Any contributions you make are greatly appreciated.

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• 🔧 Want to contribute? See CONTRIBUTING.md

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ by navadeep0508

GitHub • PyPI • Changelog • Code of Conduct