dhee 7.0.2__tar.gz → 7.2.0__tar.gz

dhee-7.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+prune dhee/ui/web/node_modules
+
+# Source distributions are driven by pyproject package discovery and explicit
+# package-data globs. Keep this file quiet unless we intentionally add broad
+# graft rules that need pruning.

dhee-7.2.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: dhee
+Version: 7.2.0
+Summary: Dhee - world memory layer and context compiler for AI agents
+Author: Sankhya AI Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sankhya-AI/Dhee
+Project-URL: Repository, https://github.com/Sankhya-AI/Dhee
+Project-URL: Issues, https://github.com/Sankhya-AI/Dhee/issues
+Project-URL: Documentation, https://github.com/Sankhya-AI/Dhee#readme
+Project-URL: Changelog, https://github.com/Sankhya-AI/Dhee/blob/main/CHANGELOG.md
+Keywords: world-memory,context-compiler,developer-brain,coding-agents,mcp,claude-code,codex,chotu,local-first,memory-layer,ai,agents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: kuzu>=0.11.3
+Requires-Dist: tree-sitter<0.26,>=0.23.2
+Requires-Dist: tree-sitter-python<0.26,>=0.23.6
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23.1
+Requires-Dist: tree-sitter-typescript<0.26,>=0.23.2
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4.0; extra == "ollama"
+Provides-Extra: nvidia
+Requires-Dist: openai>=1.0.0; extra == "nvidia"
+Provides-Extra: zvec
+Requires-Dist: zvec>=0.4.0; python_version >= "3.11" and extra == "zvec"
+Provides-Extra: sqlite-vec
+Requires-Dist: sqlite-vec>=0.1.1; extra == "sqlite-vec"
+Provides-Extra: graph
+Requires-Dist: kuzu>=0.11.3; extra == "graph"
+Provides-Extra: swe
+Requires-Dist: tree-sitter<0.26,>=0.23.2; extra == "swe"
+Requires-Dist: tree-sitter-python<0.26,>=0.23.6; extra == "swe"
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23.1; extra == "swe"
+Requires-Dist: tree-sitter-typescript<0.26,>=0.23.2; extra == "swe"
+Provides-Extra: local
+Requires-Dist: llama-cpp-python>=0.3; extra == "local"
+Requires-Dist: sentence-transformers>=3.0; extra == "local"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; python_version >= "3.10" and extra == "mcp"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100.0; extra == "api"
+Requires-Dist: uvicorn>=0.20.0; extra == "api"
+Requires-Dist: python-multipart>=0.0.9; extra == "api"
+Requires-Dist: httpx>=0.25.0; extra == "api"
+Requires-Dist: websockets>=12.0; extra == "api"
+Provides-Extra: bus
+Provides-Extra: benchmarks
+Requires-Dist: huggingface_hub>=0.24.0; extra == "benchmarks"
+Provides-Extra: edge
+Requires-Dist: onnxruntime>=1.16; extra == "edge"
+Provides-Extra: training
+Requires-Dist: unsloth; extra == "training"
+Requires-Dist: datasets>=2.0; extra == "training"
+Requires-Dist: trl>=0.7; extra == "training"
+Requires-Dist: peft>=0.6; extra == "training"
+Provides-Extra: app
+Requires-Dist: openai>=1.0.0; extra == "app"
+Requires-Dist: google-genai>=1.0.0; extra == "app"
+Requires-Dist: ollama>=0.4.0; extra == "app"
+Provides-Extra: all
+Requires-Dist: google-genai>=1.0.0; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: ollama>=0.4.0; extra == "all"
+Requires-Dist: zvec>=0.4.0; python_version >= "3.11" and extra == "all"
+Requires-Dist: mcp>=1.0.0; python_version >= "3.10" and extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: uvicorn>=0.20.0; extra == "all"
+Requires-Dist: python-multipart>=0.0.9; extra == "all"
+Requires-Dist: kuzu>=0.11.3; extra == "all"
+Requires-Dist: huggingface_hub>=0.24.0; extra == "all"
+Requires-Dist: llama-cpp-python>=0.3; extra == "all"
+Requires-Dist: sentence-transformers>=3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: openai>=1.0.0; extra == "dev"
+Requires-Dist: huggingface_hub>=0.24.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sankhya-AI/Dhee/main/docs/dhee-hero.png" alt="Dhee world memory layer for AI agents" width="100%">
+</p>
+
+<h1 align="center">Dhee</h1>
+
+<p align="center">
+  <b>World memory for AI agents.</b><br>
+  A context compiler, repo brain, narrative scene graph, handoff bus, and proof layer for Codex, Claude Code, Cursor, Gemini CLI, Cline, Chotu, and any MCP client.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dhee"><img src="https://img.shields.io/pypi/v/dhee?style=flat-square&color=orange" alt="PyPI"></a>
+  <a href="https://pypi.org/project/dhee"><img src="https://img.shields.io/badge/python-3.9%2B-blue.svg?style=flat-square" alt="Python 3.9+"></a>
+  <a href="https://github.com/Sankhya-AI/Dhee/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License"></a>
+  <a href="benchmarks/longmemeval/"><img src="https://img.shields.io/badge/LongMemEval-R%405%2099.4%25-brightgreen.svg?style=flat-square" alt="LongMemEval R@5 99.4%"></a>
+</p>
+
+---
+
+Dhee gives an agent the bigger story before it takes the next action.
+
+LLMs are powerful, but they still miss the arc. What is the user trying to become? What happened last session? Which decision was already made? Which failure should not be repeated? Which proof is required before touching code?
+
+Dhee stores that story locally and compiles it into the smallest useful context. Not a transcript pile. Not vibes. Memory with shape.
+
+## Install
+
+```bash
+pip install dhee
+dhee install
+```
+
+Or use the one-command installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Sankhya-AI/Dhee/main/install.sh | sh
+```
+
+<p align="center">
+  <img src="docs/demo/install-demo.gif" alt="Dhee curl install, provider setup, dhee init, status, and shell completion demo" width="100%">
+</p>
+
+Wire a repo:
+
+```bash
+cd /path/to/repo-or-folder
+dhee init
+dhee status
+dhee ui
+```
+
+`dhee init` is the opt-in switch. Run it in the current directory, pass a folder, or pass a git URL:
+
+```bash
+dhee init /path/to/folder
+dhee init https://github.com/org/repo.git
+```
+
+Folders that have not run `dhee init` stay vanilla in Codex and Claude Code.
+
+Shell autocomplete is built in:
+
+```bash
+dhee completion --shell zsh
+dhee completion --shell bash
+dhee completion --shell fish
+```
+
+## What Is Dhee?
+
+Dhee is the memory layer agents should have had from day one.
+
+It runs beside the model and answers the questions that raw chat history cannot:
+
+| The agent needs | Dhee gives it |
+| --- | --- |
+| What matters right now? | A compiled context packet with included and rejected reasons. |
+| What happened before? | Durable user, project, repo, scene, and handoff memory. |
+| What files are risky? | Repo brain impact analysis, likely tests, owners, routes, and symbols. |
+| What should not be used? | Secret filters, privacy classes, supersession, contradiction, and proof gates. |
+| What is the larger story? | Series, Seasons, Episodes, Scenes, and SceneCards. |
+| Can another agent continue? | Session digests, shared task state, evidence refs, and handoff packets. |
+
+## Context Compiler
+
+Most agents drown in context or starve without it. Dhee does the boring hard part in the middle.
+
+- Reads summarize files instead of dumping them.
+- Searches return compact matches with expansion pointers.
+- Tool output becomes reusable evidence, not one-turn sludge.
+- Task contracts define files, constraints, tests, and proof obligations.
+- SceneCards become the default retrieval object.
+- Raw transcripts stay out of prompts unless explicitly requested.
+
+The model gets the part of the world it needs, in the form it can use.
+
+## Narrative Memory
+
+This is the new Dhee core.
+
+```text
+Series -> Season -> Episode -> Scene -> SceneCard -> MemoryItem
+```
+
+In plain English:
+
+- **Series** is the biggest purpose. Example: become a successful CTO.
+- **Season** is a period of the story: learning, struggle, first success, downfall, comeback.
+- **Episode** is the meaningful arc of a day.
+- **Scene** is a bounded work moment with a hero, intent, action, obstacle, result, and outcome.
+- **SceneCard** is the retrieval card the agent sees later: compact, evidence-backed, privacy-aware.
+- **MemoryItem** is promoted only when the SceneCard is worth keeping long-term.
+
+That story gives the model anticipation. The prior is advisory, never bossy: explicit user intent, facts, privacy, and proof gates win.
+
+## Retrieval That Actually Ranks
+
+Dhee can run model-free, but the production retrieval path is built for serious agent work:
+
+```bash
+python3.11 -m pip install "dhee[nvidia,zvec,mcp]"
+dhee key set nvidia
+```
+
+Current high-quality stack:
+
+- Embedder: `nvidia/llama-nemotron-embed-vl-1b-v2`
+- Reranker: `nvidia/llama-3.2-nv-rerankqa-1b-v2`
+- Vector backend: `zvec` through `dhee-accel`
+- Routine narrative rollups: `google/gemma-4-31b-it`
+- Series-level strategic rollups: `moonshotai/kimi-k2.6`
+
+Deterministic filters still go first: secrets, private scenes, contradicted cards, superseded cards, and code-mutation proof gates cannot be talked around by a high similarity score.
+
+## MCP Tools
+
+Add Dhee to any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "dhee": { "command": "dhee-mcp" }
+  }
+}
+```
+
+Scene intelligence tools:
+
+```text
+dhee_scene_start
+dhee_scene_event
+dhee_scene_end
+dhee_scene_context
+dhee_narrative_prior
+```
+
+Core context tools:
+
+```text
+dhee_context_bootstrap
+dhee_read
+dhee_grep
+dhee_bash
+dhee_context_pack
+dhee_scene_search
+```
+
+A good agent loop is simple:
+
+```text
+bootstrap -> start scene -> gather evidence -> retrieve context -> act -> verify -> end scene -> save digest
+```
+
+## Repo Brain
+
+Ask: "If I touch this file, what breaks?"
+
+Dhee's repo brain answers with graph-backed evidence:
+
+- impacted files and symbols
+- impacted routes and React components
+- likely tests to run
+- owners from git history
+- related failure signatures
+- source windows with line numbers
+
+The repo brain is git-SHA scoped and persisted under `.dhee/context/repo_brain/`, so the agent does not rebuild the same understanding every session.
+
+## Why It Feels Different
+
+Normal memory says: "Here are some old notes."
+
+Dhee says:
+
+- this is the user's bigger goal
+- this is the current season of work
+- this is today's episode
+- this scene has these constraints
+- these cards are safe to use
+- these cards were rejected and why
+- this action needs proof before mutation
+
+The result is an agent that feels less random because it can see the arc.
+
+## Benchmarks
+
+On LongMemEval full 500-question recall:
+
+| System | R@1 | R@3 | R@5 | R@10 |
+| --- | ---: | ---: | ---: | ---: |
+| Dhee | 94.8% | 99.0% | 99.4% | 99.8% |
+
+Reproduction notes and outputs live in [`benchmarks/longmemeval/`](benchmarks/longmemeval/).
+
+## What Ships
+
+The open source package includes the local memory OS, context compiler, DheeFS, MCP servers, CLI, UI, runtime daemon, handoff bus, repo brain, update capsules, narrative scene intelligence, release checks, and proof tooling.
+
+Team governance, hosted dashboards, org policy, and managed source connectors can build on top of these local primitives. Dhee itself is useful without a hosted account.
+
+## Develop
+
+```bash
+python3.11 -m pip install -e ".[dev,nvidia,zvec,mcp]"
+pytest
+```
+
+Focused release checks:
+
+```bash
+python -m pytest tests/test_narrative_scene_intelligence.py tests/test_mcp_tools_slim.py tests/test_scene.py tests/test_temporal_scenes.py tests/test_reranker_defaults.py tests/test_nvidia_embedder.py -q
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+MIT. Built by Sankhya AI Labs.

dhee-7.2.0/README.md

@@ -0,0 +1,239 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sankhya-AI/Dhee/main/docs/dhee-hero.png" alt="Dhee world memory layer for AI agents" width="100%">
+</p>
+
+<h1 align="center">Dhee</h1>
+
+<p align="center">
+  <b>World memory for AI agents.</b><br>
+  A context compiler, repo brain, narrative scene graph, handoff bus, and proof layer for Codex, Claude Code, Cursor, Gemini CLI, Cline, Chotu, and any MCP client.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dhee"><img src="https://img.shields.io/pypi/v/dhee?style=flat-square&color=orange" alt="PyPI"></a>
+  <a href="https://pypi.org/project/dhee"><img src="https://img.shields.io/badge/python-3.9%2B-blue.svg?style=flat-square" alt="Python 3.9+"></a>
+  <a href="https://github.com/Sankhya-AI/Dhee/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License"></a>
+  <a href="benchmarks/longmemeval/"><img src="https://img.shields.io/badge/LongMemEval-R%405%2099.4%25-brightgreen.svg?style=flat-square" alt="LongMemEval R@5 99.4%"></a>
+</p>
+
+---
+
+Dhee gives an agent the bigger story before it takes the next action.
+
+LLMs are powerful, but they still miss the arc. What is the user trying to become? What happened last session? Which decision was already made? Which failure should not be repeated? Which proof is required before touching code?
+
+Dhee stores that story locally and compiles it into the smallest useful context. Not a transcript pile. Not vibes. Memory with shape.
+
+## Install
+
+```bash
+pip install dhee
+dhee install
+```
+
+Or use the one-command installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Sankhya-AI/Dhee/main/install.sh | sh
+```
+
+<p align="center">
+  <img src="docs/demo/install-demo.gif" alt="Dhee curl install, provider setup, dhee init, status, and shell completion demo" width="100%">
+</p>
+
+Wire a repo:
+
+```bash
+cd /path/to/repo-or-folder
+dhee init
+dhee status
+dhee ui
+```
+
+`dhee init` is the opt-in switch. Run it in the current directory, pass a folder, or pass a git URL:
+
+```bash
+dhee init /path/to/folder
+dhee init https://github.com/org/repo.git
+```
+
+Folders that have not run `dhee init` stay vanilla in Codex and Claude Code.
+
+Shell autocomplete is built in:
+
+```bash
+dhee completion --shell zsh
+dhee completion --shell bash
+dhee completion --shell fish
+```
+
+## What Is Dhee?
+
+Dhee is the memory layer agents should have had from day one.
+
+It runs beside the model and answers the questions that raw chat history cannot:
+
+| The agent needs | Dhee gives it |
+| --- | --- |
+| What matters right now? | A compiled context packet with included and rejected reasons. |
+| What happened before? | Durable user, project, repo, scene, and handoff memory. |
+| What files are risky? | Repo brain impact analysis, likely tests, owners, routes, and symbols. |
+| What should not be used? | Secret filters, privacy classes, supersession, contradiction, and proof gates. |
+| What is the larger story? | Series, Seasons, Episodes, Scenes, and SceneCards. |
+| Can another agent continue? | Session digests, shared task state, evidence refs, and handoff packets. |
+
+## Context Compiler
+
+Most agents drown in context or starve without it. Dhee does the boring hard part in the middle.
+
+- Reads summarize files instead of dumping them.
+- Searches return compact matches with expansion pointers.
+- Tool output becomes reusable evidence, not one-turn sludge.
+- Task contracts define files, constraints, tests, and proof obligations.
+- SceneCards become the default retrieval object.
+- Raw transcripts stay out of prompts unless explicitly requested.
+
+The model gets the part of the world it needs, in the form it can use.
+
+## Narrative Memory
+
+This is the new Dhee core.
+
+```text
+Series -> Season -> Episode -> Scene -> SceneCard -> MemoryItem
+```
+
+In plain English:
+
+- **Series** is the biggest purpose. Example: become a successful CTO.
+- **Season** is a period of the story: learning, struggle, first success, downfall, comeback.
+- **Episode** is the meaningful arc of a day.
+- **Scene** is a bounded work moment with a hero, intent, action, obstacle, result, and outcome.
+- **SceneCard** is the retrieval card the agent sees later: compact, evidence-backed, privacy-aware.
+- **MemoryItem** is promoted only when the SceneCard is worth keeping long-term.
+
+That story gives the model anticipation. The prior is advisory, never bossy: explicit user intent, facts, privacy, and proof gates win.
+
+## Retrieval That Actually Ranks
+
+Dhee can run model-free, but the production retrieval path is built for serious agent work:
+
+```bash
+python3.11 -m pip install "dhee[nvidia,zvec,mcp]"
+dhee key set nvidia
+```
+
+Current high-quality stack:
+
+- Embedder: `nvidia/llama-nemotron-embed-vl-1b-v2`
+- Reranker: `nvidia/llama-3.2-nv-rerankqa-1b-v2`
+- Vector backend: `zvec` through `dhee-accel`
+- Routine narrative rollups: `google/gemma-4-31b-it`
+- Series-level strategic rollups: `moonshotai/kimi-k2.6`
+
+Deterministic filters still go first: secrets, private scenes, contradicted cards, superseded cards, and code-mutation proof gates cannot be talked around by a high similarity score.
+
+## MCP Tools
+
+Add Dhee to any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "dhee": { "command": "dhee-mcp" }
+  }
+}
+```
+
+Scene intelligence tools:
+
+```text
+dhee_scene_start
+dhee_scene_event
+dhee_scene_end
+dhee_scene_context
+dhee_narrative_prior
+```
+
+Core context tools:
+
+```text
+dhee_context_bootstrap
+dhee_read
+dhee_grep
+dhee_bash
+dhee_context_pack
+dhee_scene_search
+```
+
+A good agent loop is simple:
+
+```text
+bootstrap -> start scene -> gather evidence -> retrieve context -> act -> verify -> end scene -> save digest
+```
+
+## Repo Brain
+
+Ask: "If I touch this file, what breaks?"
+
+Dhee's repo brain answers with graph-backed evidence:
+
+- impacted files and symbols
+- impacted routes and React components
+- likely tests to run
+- owners from git history
+- related failure signatures
+- source windows with line numbers
+
+The repo brain is git-SHA scoped and persisted under `.dhee/context/repo_brain/`, so the agent does not rebuild the same understanding every session.
+
+## Why It Feels Different
+
+Normal memory says: "Here are some old notes."
+
+Dhee says:
+
+- this is the user's bigger goal
+- this is the current season of work
+- this is today's episode
+- this scene has these constraints
+- these cards are safe to use
+- these cards were rejected and why
+- this action needs proof before mutation
+
+The result is an agent that feels less random because it can see the arc.
+
+## Benchmarks
+
+On LongMemEval full 500-question recall:
+
+| System | R@1 | R@3 | R@5 | R@10 |
+| --- | ---: | ---: | ---: | ---: |
+| Dhee | 94.8% | 99.0% | 99.4% | 99.8% |
+
+Reproduction notes and outputs live in [`benchmarks/longmemeval/`](benchmarks/longmemeval/).
+
+## What Ships
+
+The open source package includes the local memory OS, context compiler, DheeFS, MCP servers, CLI, UI, runtime daemon, handoff bus, repo brain, update capsules, narrative scene intelligence, release checks, and proof tooling.
+
+Team governance, hosted dashboards, org policy, and managed source connectors can build on top of these local primitives. Dhee itself is useful without a hosted account.
+
+## Develop
+
+```bash
+python3.11 -m pip install -e ".[dev,nvidia,zvec,mcp]"
+pytest
+```
+
+Focused release checks:
+
+```bash
+python -m pytest tests/test_narrative_scene_intelligence.py tests/test_mcp_tools_slim.py tests/test_scene.py tests/test_temporal_scenes.py tests/test_reranker_defaults.py tests/test_nvidia_embedder.py -q
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+MIT. Built by Sankhya AI Labs.

{dhee-7.0.2 → dhee-7.2.0}/dhee/__init__.py

@@ -1,7 +1,8 @@
-"""dhee — the local developer brain for AI coding agents.
+"""dhee - the world memory layer and context compiler for AI agents.
 
-Dhee gives Codex, Claude Code, Cursor, Cline, Gemini CLI, and MCP clients a
-shared memory, repo-cognition, handoff, and proof layer that survives sessions.
+Dhee gives Codex, Claude Code, Cursor, Cline, Gemini CLI, Chotu, and MCP
+clients durable memory, repo cognition, narrative scene intelligence, handoff,
+proof, and prompt-safe context that survives sessions.
 
 Quick Start:
     from dhee import Dhee
@@ -40,7 +41,7 @@ from dhee.memory.admission import (
 # Default import remains model-free for backwards compatibility.
 Memory = CoreMemory
 
-__version__ = "7.0.2"
+__version__ = "7.2.0"
 __all__ = [
     # Memory classes
     "Engram",