kryth 0.1.0__tar.gz

kryth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kryth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kryth-0.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+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>

kryth-0.1.0/README.md

@@ -0,0 +1,276 @@
+<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>

kryth-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kryth"
+version = "0.1.0"
+description = "AI Agent Memory Framework — structured memory layers for LLM-based agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+keywords = ["ai", "agent", "memory", "llm", "framework"]
+
+authors = [
+    {name = "Kryth Contributors"},
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.7",
+    "pre-commit>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["kryth*"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

kryth-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kryth-0.1.0/src/kryth/__init__.py

@@ -0,0 +1,31 @@
+"""Kryth — AI Agent Memory Framework.
+
+Kryth provides structured memory layers for LLM-based agents, including
+write, retrieval, duplicate detection, and compression controllers.
+
+Typical usage::
+
+    from kryth.agent.memory.controllers import (
+        WriteController,
+        RetrievalController,
+        DuplicateDetector,
+        CompressionController,
+        compute_state_hash,
+    )
+"""
+
+from kryth.agent.memory.controllers import (
+    CompressionController,
+    DuplicateDetector,
+    RetrievalController,
+    WriteController,
+    compute_state_hash,
+)
+
+__all__ = [
+    "WriteController",
+    "RetrievalController",
+    "DuplicateDetector",
+    "CompressionController",
+    "compute_state_hash",
+]

kryth-0.1.0/src/kryth/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent memory subpackage for Kryth."""