Metadata-Version: 2.4
Name: kryth
Version: 0.1.0
Summary: AI Agent Memory Framework — structured memory layers for LLM-based agents
Author: Kryth Contributors
License: MIT
Keywords: ai,agent,memory,llm,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <br/>
  <h1>🧠 Kryth</h1>
  <p><strong>AI Agent Memory Framework — Structured memory layers for LLM-based agents</strong></p>

  <br/>

  <!-- Badges -->
  <p>
    <a href="https://pypi.org/project/kryth/">
      <img src="https://img.shields.io/pypi/v/kryth?style=for-the-badge&logo=pypi&logoColor=white&color=blueviolet" alt="PyPI Version"/>
    </a>
    <a href="https://pypi.org/project/kryth/">
      <img src="https://img.shields.io/pypi/dm/kryth?style=for-the-badge&logo=python&logoColor=white&color=blue" alt="PyPI Downloads"/>
    </a>
    <a href="LICENSE">
      <img src="https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge" alt="MIT License"/>
    </a>
    <a href="https://github.com/navadeep0508/KRYTH-OS">
      <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"/>
    </a>
    <a href="https://github.com/navadeep0508/KRYTH-OS/actions">
      <img src="https://img.shields.io/badge/code%20style-ruff-261230?style=for-the-badge&logo=ruff&logoColor=white" alt="Ruff"/>
    </a>
    <a href="CONTRIBUTING.md">
      <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge&logo=github" alt="PRs Welcome"/>
    </a>
  </p>

  <br/>

  <!-- Quick links -->
  <p>
    <a href="#-quick-start">🚀 Quick Start</a> •
    <a href="#-features">✨ Features</a> •
    <a href="#-architecture">🏗️ Architecture</a> •
    <a href="#-installation">📦 Installation</a> •
    <a href="#-contributing">🤝 Contributing</a>
  </p>

  <br/>
</div>

---

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

```python
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

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

---

## 🏗️ Architecture

Kryth organizes memory into a clean, layered architecture:

```mermaid
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):

```bash
pip install kryth
```

**Development version**:

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

---

## 🧪 Development

```bash
# 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

- [x] Core memory controllers (Write, Retrieve, Deduplicate, Compress)
- [x] 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](https://github.com/navadeep0508/KRYTH-OS/issues)
- 💡 Have an idea? [Start a discussion](https://github.com/navadeep0508/KRYTH-OS/discussions)
- 🔧 Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 📄 License

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

---

<div align="center">
  <p>
    Made with ❤️ by <a href="https://github.com/navadeep0508">navadeep0508</a>
  </p>
  <p>
    <a href="https://github.com/navadeep0508/KRYTH-OS">GitHub</a> •
    <a href="https://pypi.org/project/kryth/">PyPI</a> •
    <a href="CHANGELOG.md">Changelog</a> •
    <a href="CODE_OF_CONDUCT.md">Code of Conduct</a>
  </p>
</div>
