kryth 0.1.0__py3-none-any.whl

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/agent/__init__.py

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

kryth/agent/memory/__init__.py

@@ -0,0 +1,21 @@
+"""Memory controllers subpackage for Kryth.
+
+Exports: 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/agent/memory/controllers.py

@@ -0,0 +1,415 @@
+"""Memory controllers — Write, Retrieval, DuplicateDetector, Compression.
+
+Every tool call that produces knowledge must go through WriteController.
+Every prompt injection must go through RetrievalController.
+Every duplicate check must go through DuplicateDetector.
+Memory growth is managed by CompressionController.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ── State hash ──────────────────────────────────────────────────────────
+
+def compute_state_hash(cwd: str = "") -> str:
+    """Compute a robust state hash for duplicate command detection.
+
+    Includes:
+      1. git diff (staged + unstaged)
+      2. modified file hashes (up to 20)
+      3. dependency lock file hashes
+      4. environment hash (selected vars)
+      5. working directory
+    """
+    hasher = hashlib.sha256()
+    cwd = cwd or os.getcwd()
+    hasher.update(cwd.encode())
+
+    # 1. Git diff
+    try:
+        diff = subprocess.run(
+            ["git", "diff", "--no-color"],
+            capture_output=True, text=True, timeout=5, cwd=cwd,
+        )
+        hasher.update(diff.stdout.encode()[:50000])
+        diff_staged = subprocess.run(
+            ["git", "diff", "--no-color", "--cached"],
+            capture_output=True, text=True, timeout=5, cwd=cwd,
+        )
+        hasher.update(diff_staged.stdout.encode()[:50000])
+    except Exception:
+        pass
+
+    # 2. Modified file hashes (up to 20 files by mtime)
+    try:
+        lock_files = [
+            "requirements.txt", "Pipfile", "Pipfile.lock",
+            "pyproject.toml", "poetry.lock",
+            "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
+            "Cargo.toml", "Cargo.lock",
+            "go.mod", "go.sum",
+            "Gemfile", "Gemfile.lock",
+            "composer.json", "composer.lock",
+        ]
+        counted = 0
+        for fname in lock_files:
+            fpath = Path(cwd) / fname
+            if fpath.is_file():
+                try:
+                    h = hashlib.sha256(fpath.read_bytes()).hexdigest()[:16]
+                    hasher.update(f"{fname}:{h}".encode())
+                    counted += 1
+                except Exception:
+                    pass
+        # Recent modified files
+        for f in sorted(Path(cwd).iterdir(), key=lambda p: p.stat().st_mtime if p.is_file() else 0, reverse=True)[:20]:
+            if f.is_file() and f.suffix in (".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".java"):
+                try:
+                    h = hashlib.sha256(f.read_bytes()).hexdigest()[:16]
+                    hasher.update(f"{f.name}:{h}".encode())
+                    counted += 1
+                except Exception:
+                    pass
+    except Exception:
+        pass
+
+    # 3. Environment hash (selected vars — not secrets)
+    for var in ("VIRTUAL_ENV", "CONDA_PREFIX", "NODE_ENV", "PYTHON_VERSION", "NODE_VERSION"):
+        val = os.environ.get(var, "")
+        if val:
+            hasher.update(f"{var}={val}".encode())
+
+    return hasher.hexdigest()[:16]
+
+
+# ── Duplicate Detector ──────────────────────────────────────────────────
+
+class DuplicateDetector:
+    """Soft duplicate detection — returns memory summaries, never hard-blocks.
+
+    Rules:
+      - Same file + same hash → return memory summary, allow reread
+      - Same command + same cwd + same state_hash → return previous result, allow rerun
+    """
+
+    def check_read(self, repo_memory, session_id: int, path: str) -> Optional[dict]:
+        """Check if file was already read. Returns a memory hit dict or None."""
+        file_rec = repo_memory.get_file(session_id, path)
+        if not file_rec:
+            return None
+        try:
+            with open(path, "rb") as f:
+                current_hash = hashlib.sha256(f.read()).hexdigest()[:16]
+            if current_hash != file_rec.hash:
+                return None  # file changed, not a duplicate
+        except Exception:
+            return None
+
+        summary = self._build_read_summary(file_rec)
+        return {
+            "duplicate": True,
+            "type": "read",
+            "path": path,
+            "turn": file_rec.last_read_turn,
+            "read_count": file_rec.read_count,
+            "summary": summary,
+        }
+
+    def _build_read_summary(self, rec) -> str:
+        """Build a concise semantic summary of what's already known about a file."""
+        parts = [f"📄 {rec.path} ({rec.language}, {rec.lines} lines, read #{rec.read_count})"]
+        if rec.purpose:
+            parts.append(f"   Purpose: {rec.purpose[:80]}")
+        if rec.functions:
+            parts.append(f"   Functions: {', '.join(rec.functions[:8])}")
+        if rec.classes:
+            parts.append(f"   Classes: {', '.join(rec.classes[:5])}")
+        if rec.routes:
+            parts.append(f"   Routes: {', '.join(rec.routes[:8])}")
+        if rec.imports:
+            parts.append(f"   Imports: {', '.join(rec.imports[:6])}")
+        return "\n".join(parts)
+
+    def check_command(
+        self, execution_memory, session_id: int, command: str, cwd: str, state_hash: str = ""
+    ) -> Optional[dict]:
+        """Check if identical command was already run. Returns a memory hit dict or None."""
+        dup = execution_memory.find_duplicate(session_id, command, cwd, state_hash)
+        if dup is None:
+            return None
+        return {
+            "duplicate": True,
+            "type": "command",
+            "command": command[:80],
+            "exit_code": dup.exit_code,
+            "status": "success" if dup.exit_code == 0 else "failed",
+            "previous_output": dup.output_summary[:200],
+            "run_count": dup.run_count,
+        }
+
+
+# ── Write Controller ────────────────────────────────────────────────────
+
+class WriteController:
+    """Single writer for all memory layers.
+
+    Tool → Memory mapping:
+      read_file            → RepoMemory
+      run_command          → ExecutionMemory (with state_hash)
+      edit_file/multi_edit → RepoMemory (invalidate) + EpisodicMemory
+      run_tests            → EpisodicMemory
+    """
+
+    def on_tool_result(
+        self,
+        tool_name: str,
+        args: dict,
+        result: Any,
+        error: bool,
+        session_id: int,
+        memory_manager,
+        turn: int,
+    ) -> None:
+        if error:
+            return
+
+        if tool_name == "read_file":
+            path = args.get("path", "")
+            if path and result:
+                content = str(result)
+                memory_manager.repo.add_file(session_id, path, content, turn)
+                memory_manager.working.add_finding(f"Read: {path}")
+
+        elif tool_name in ("run_command", "shell_exec"):
+            command = args.get("command", "") or args.get("cmd", "")
+            cwd = args.get("cwd") or os.getcwd()
+            exit_code = 0
+            output_summary = str(result)[:500] if result else ""
+            if "ERROR" in output_summary.upper() or "FAILED" in output_summary.upper():
+                exit_code = 1
+            env_hash = hashlib.sha256(str(sorted(os.environ.items())).encode()).hexdigest()[:16]
+            state_hash = compute_state_hash(cwd)
+            memory_manager.execution.record(
+                session_id, command, cwd, exit_code, output_summary,
+                env_hash=env_hash, state_hash=state_hash,
+            )
+
+        elif tool_name in ("edit_file", "multi_edit"):
+            path = args.get("path", "")
+            if path:
+                memory_manager.repo.invalidate_file(session_id, path)
+                desc = args.get("oldString", "")[:60] or args.get("newString", "")[:60]
+                desc = desc or f"edit {os.path.basename(path)}"
+                memory_manager.episodic.add_edit(session_id, path, desc)
+
+        elif tool_name == "write_file":
+            path = args.get("path", "")
+            if path:
+                memory_manager.repo.invalidate_file(session_id, path)
+                memory_manager.episodic.add_edit(session_id, path, "wrote file")
+
+        elif tool_name in ("run_tests",):
+            memory_manager.episodic.add_result(session_id, str(result)[:200] if result else "tests completed")
+
+    def set_objective(self, memory_manager, session_id: int, objective: str) -> None:
+        memory_manager.working.set_objective(objective)
+        if session_id:
+            try:
+                memory_manager.episodic.set_objective(session_id, objective)
+            except Exception:
+                pass
+
+
+# ── Retrieval Controller ────────────────────────────────────────────────
+
+class RetrievalController:
+    """Retrieve only relevant memory for LLM context injection.
+
+    Strictly capped at 800 tokens (~3200 chars).
+    Priority order:
+      1. Current objective
+      2. WorkingMemory findings + blockers
+      3. Top repo memory hits (ranked by importance)
+      4. Recent command results
+      5. Critical episodic findings
+    """
+
+    MAX_CHARS = 3200  # ~800 tokens
+
+    # Keyword → relevance mapping for scoring repo files
+    _RELEVANCE_KEYWORDS = {
+        "auth": ["login", "auth", "oauth", "session", "token", "password", "user", "permission", "jwt"],
+        "api": ["route", "api", "endpoint", "rest", "controller", "handler", "middleware"],
+        "db": ["db", "database", "sql", "model", "schema", "migration", "query", "orm"],
+        "config": ["config", "setting", "env", "yaml", "json", "toml", "ini"],
+        "test": ["test", "spec", "mock", "assert", "pytest", "jest"],
+        "frontend": ["component", "react", "vue", "svelte", "template", "css", "html", "ui"],
+        "build": ["build", "webpack", "vite", "rollup", "babel", "tsconfig", "make"],
+        "deploy": ["deploy", "docker", "ci", "cd", "pipeline", "action", "workflow"],
+    }
+
+    def build_prompt_block(
+        self,
+        memory_manager,
+        session_id: int,
+        include_long_term: bool = False,
+        user_input: str = "",
+    ) -> str:
+        parts = []
+
+        # 1. Current objective (always included, highest priority)
+        wm = memory_manager.working.to_prompt_block(max_chars=600)
+        if wm:
+            parts.append(wm)
+
+        remaining = self.MAX_CHARS - sum(len(p) + 2 for p in parts)
+
+        # 2. Repo memory — ranked by importance + relevance
+        repo = self._get_repo_block(memory_manager, session_id, user_input, max_chars=min(remaining, 1200))
+        if repo:
+            parts.append(repo)
+            remaining = self.MAX_CHARS - sum(len(p) + 2 for p in parts)
+
+        # 3. Recent command results (compact)
+        exec_block = memory_manager.execution.get_prompt_block(session_id)
+        if exec_block:
+            if len(exec_block) + 2 > remaining:
+                exec_lines = exec_block.splitlines()
+                exec_block = "\n".join(exec_lines[:4])  # keep only header + 3 results
+                if len(exec_block) + 2 > remaining:
+                    exec_block = exec_block[:remaining - 2]
+            if exec_block:
+                parts.append(exec_block)
+                remaining = self.MAX_CHARS - sum(len(p) + 2 for p in parts)
+
+        # 4. Episodic findings (compact)
+        ep = memory_manager.episodic.get_prompt_block(max_chars=min(remaining, 800))
+        if ep:
+            parts.append(ep)
+            remaining = self.MAX_CHARS - sum(len(p) + 2 for p in parts)
+
+        # 5. Long-term memory (if requested, lowest priority)
+        if include_long_term and remaining > 200:
+            ltm = memory_manager.long_term.to_prompt_block(max_chars=min(remaining, 400))
+            if ltm:
+                parts.append(ltm)
+
+        block = "\n\n".join(parts)
+        if len(block) > self.MAX_CHARS:
+            block = block[:self.MAX_CHARS] + "\n... (truncated)"
+        return block
+
+    def _get_repo_block(
+        self, memory_manager, session_id: int, user_input: str, max_chars: int
+    ) -> str:
+        """Retrieve repo memory ranked by importance + relevance."""
+        mem = memory_manager.repo._get(session_id)
+        if not mem.files:
+            return ""
+
+        # Score files by relevance
+        query_tokens = set(re.findall(r'\w+', user_input.lower())) if user_input else set()
+        scored = []
+        for path, rec in mem.files.items():
+            relevance = self._compute_relevance(rec, query_tokens) if query_tokens else 0.5
+            score = 0.7 * rec.importance_score + 0.3 * relevance
+            scored.append((score, path, rec))
+
+        # Sort by score descending
+        scored.sort(key=lambda x: -x[0])
+
+        parts = ["KNOWN REPO STATE"]
+        if mem.framework:
+            parts.append(f"Framework: {mem.framework}")
+
+        # Top files by score
+        file_lines = []
+        for score, path, rec in scored[:8]:
+            desc = f"  {path} ({rec.language}, {rec.lines} lines, imp={score:.2f})"
+            if rec.purpose:
+                desc += f" — {rec.purpose[:50]}"
+            file_lines.append(desc)
+        if file_lines:
+            parts.append(f"Files ({len(mem.files)}):\n" + "\n".join(file_lines))
+
+        # Key symbols from top files
+        sym_lines = []
+        for score, path, rec in scored[:5]:
+            syms = (rec.functions + rec.classes)[:6]
+            if syms:
+                sym_lines.append(f"  {path}: {', '.join(syms)}")
+        if sym_lines:
+            parts.append("Key symbols:\n" + "\n".join(sym_lines))
+
+        if mem.entrypoints:
+            parts.append("Entry points:\n  " + "\n  ".join(mem.entrypoints[:3]))
+
+        if mem.routes:
+            parts.append("Routes:\n  " + ", ".join(mem.routes[:10]))
+
+        block = "\n\n".join(parts)
+        if len(block) > max_chars:
+            return block[:max_chars] + "\n... (truncated)"
+        return block
+
+    @staticmethod
+    def _compute_relevance(rec, query_tokens: set) -> float:
+        """Score how relevant a file record is to the user's query tokens."""
+        if not query_tokens:
+            return 0.0
+        text = f"{rec.path} {rec.purpose} {' '.join(rec.functions)} {' '.join(rec.classes)} {' '.join(rec.imports)}".lower()
+        matches = sum(1 for t in query_tokens if t in text or any(t in w for w in text.split()))
+        return min(1.0, matches / max(1, len(query_tokens)))
+
+    def get_priority_ranking(
+        self,
+        memory_manager,
+        session_id: int,
+        user_input: str = "",
+    ) -> dict[str, str]:
+        return {
+            "objective": memory_manager.working.objective,
+            "repo_files": str(len(memory_manager.repo._get(session_id).files)),
+            "recent_commands": str(len(memory_manager.execution._get(session_id).commands)),
+            "findings": str(len(memory_manager.episodic._get(session_id).root_causes)),
+        }
+
+
+# ── Compression Controller ──────────────────────────────────────────────
+
+class CompressionController:
+    """Prevent uncontrolled memory growth."""
+
+    def compress_episodic(self, episodic_memory, session_id: int) -> None:
+        episode = episodic_memory._get(session_id)
+        if len(episode.root_causes) > 10:
+            episode.root_causes = episode.root_causes[-10:]
+        if len(episode.hypotheses) > 10:
+            episode.hypotheses = episode.hypotheses[-10:]
+        if len(episode.edits) > 20:
+            episode.edits = episode.edits[-20:]
+        if len(episode.decisions) > 20:
+            episode.decisions = episode.decisions[-20:]
+        if len(episode.successful_strategies) > 10:
+            episode.successful_strategies = episode.successful_strategies[-10:]
+        if len(episode.failed_strategies) > 10:
+            episode.failed_strategies = episode.failed_strategies[-10:]
+
+    def compress_long_term(self, long_term_memory) -> int:
+        return long_term_memory.compress(keep_top=500)
+
+    def compress_execution(self, execution_memory, session_id: int) -> None:
+        mem = execution_memory._get(session_id)
+        if len(mem.commands) > mem.max_commands:
+            mem.commands = mem.commands[-mem.max_commands:]
+            keys = list(mem._index.keys())
+            for k in keys[:max(0, len(keys) - mem.max_commands)]:
+                mem._index.pop(k, None)

kryth-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+kryth/__init__.py,sha256=2_ni1dmz-5K6y0f6gKEkJHySLn50iXNv1o8RzkFetZc,711
+kryth/agent/__init__.py,sha256=xbT9pJFwCWRps32v6y1s0VAUAEzpEqKKdz2wlc2008Y,41
+kryth/agent/memory/__init__.py,sha256=moq3lqQheZvNTkzByYrWuUyORnl22VY9yPewCr39VkA,471
+kryth/agent/memory/controllers.py,sha256=w9JQEsghyGK53LmS9NuFctrSnhs198piXhvyhqEwHwE,16685
+kryth-0.1.0.dist-info/licenses/LICENSE,sha256=NAbUpPHgo4xtuaN2PlRZWE6-cSxhMaTybd4hc--PjGs,1062
+kryth-0.1.0.dist-info/METADATA,sha256=_Fde4EWZ7L7PEBN1A7jBijC2KRaA0ShUrHgm2ht28G0,9323
+kryth-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+kryth-0.1.0.dist-info/top_level.txt,sha256=8gUYy5gbkp2v_rDrvdeipvrt5u7eJwjstnnRPXVRrgw,6
+kryth-0.1.0.dist-info/RECORD,,

kryth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kryth-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+kryth