dhee 2.0.0__tar.gz → 3.0.0__tar.gz

{dhee-2.0.0 → dhee-3.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dhee
-Version: 2.0.0
-Summary: Self-Evolving Cognition Plugin — makes ANY agent a self-improving HyperAgent
+Version: 3.0.0
+Summary: Cognition layer for AI agents — persistent memory, performance tracking, and insight synthesis
 Author: Sankhya AI Labs
 License: MIT
 Project-URL: Homepage, https://github.com/Sankhya-AI/Dhee
@@ -10,7 +10,7 @@ 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: memory-layer,cognition,mcp,self-evolving,hyperagent,ai,agents,plugin,llm,edge
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -79,7 +79,7 @@ Dynamic: license-file
 <h3 align="center">The cognition layer that turns your agent into a HyperAgent.</h3>
 
 <p align="center">
-  4 tools. 1 LLM call per session. ~$0.004 total cost.<br>
+  4-operation API. Deferred enrichment. Minimal hot-path cost.<br>
   Your agent remembers, learns from outcomes, and predicts what you need next.
 </p>
 
@@ -105,9 +105,17 @@ Most memory layers are glorified vector stores. Store text, retrieve text. Your
 
 ### Benchmark: LongMemEval
 
-Dhee achieves near-perfect retrieval on [LongMemEval](https://arxiv.org/abs/2410.10813), the standard benchmark for long-term conversational memory — temporal reasoning, multi-session aggregation, knowledge updates, and counterfactual tracking across 500+ questions.
+Dhee is being evaluated on [LongMemEval](https://arxiv.org/abs/2410.10813), the standard benchmark for long-term conversational memory — temporal reasoning, multi-session aggregation, knowledge updates, and counterfactual tracking across 500+ questions. Preliminary results are promising.
 
-> Evaluation run in progress. Full results and methodology will be published in the benchmark report.
+> Full methodology and results will be published in the benchmark report.
+
+---
+
+## Status
+
+Dhee is **experimental software under active development**. The core 4-operation API (`remember`/`recall`/`context`/`checkpoint`) is stable. Advanced subsystems (belief tracking, policy extraction, episodic indexing) are functional but evolving.
+
+Use it. Build on it. But know that internals will change.
 
 ---
 
@@ -165,7 +173,7 @@ Every interface — MCP, Python, CLI, JS — exposes the same 4 operations.
 ### `remember(content)`
 Store a fact, preference, or observation.
 
-**Hot path**: 0 LLM calls, 1 embedding (~$0.0002). The memory is stored immediately. Echo enrichment (paraphrases, keywords, question-forms that make future recall dramatically better) is deferred to `checkpoint`.
+**Hot path**: 0 LLM calls, 1 embedding (~$0.0002 typical). The memory is stored immediately. Echo enrichment (paraphrases, keywords, question-forms that make future recall dramatically better) is deferred to `checkpoint`.
 
 ```python
 d.remember("User prefers FastAPI over Flask")
@@ -175,7 +183,7 @@ d.remember("Project uses PostgreSQL 15 with pgvector")
 ### `recall(query)`
 Search memory. Returns top-K results ranked by relevance.
 
-**Hot path**: 0 LLM calls, 1 embedding (~$0.0002). Pure vector search with echo-boosted re-ranking.
+**Hot path**: 0 LLM calls, 1 embedding (~$0.0002 typical). Pure vector search with echo-boosted re-ranking.
 
 ```python
 results = d.recall("what database does the project use?")
@@ -233,6 +241,8 @@ d.checkpoint(
 | `checkpoint` | 1 per ~10 memories | 0 | ~$0.001 |
 | **Typical session** | **1** | **~15** | **~$0.004** |
 
+> Costs assume OpenAI `text-embedding-3-small` at current pricing. Actual costs vary by provider, model, and configuration.
+
 ---
 
 ## How It Works (Under the Hood)
@@ -250,7 +260,7 @@ Stores memories in SQLite + a vector index. On the hot path (`remember`/`recall`
 
 All of this happens in **1 LLM call per ~10 memories**. Not 4 calls per memory. One batched call.
 
-Memory decays naturally (Ebbinghaus curve). Frequently accessed memories get promoted from short-term to long-term. Unused ones fade. ~45% less storage than systems that keep everything forever.
+Memory decays naturally (Ebbinghaus curve). Frequently accessed memories get promoted from short-term to long-term. Unused ones fade. Storage naturally reduces over time as unused memories decay, unlike systems that keep everything indefinitely.
 
 ### Cognition Engine — Buddhi
 
@@ -265,6 +275,17 @@ Zero LLM calls on the hot path. Pure pattern matching + statistics. Persistence
 
 Inspired by [Meta's DGM-Hyperagents](https://arxiv.org/abs/2603.19461) — agents that emergently develop persistent memory and performance tracking achieve self-accelerating improvement that transfers across domains. Dhee provides these capabilities as infrastructure.
 
+#### Experimental Extensions
+
+Beyond the core cognition engine, Dhee includes experimental subsystems that are functional but still evolving:
+
+- **Belief store** — confidence-tracked facts with Bayesian updates and contradiction detection
+- **Policy store** — outcome-linked condition→action rules extracted from task completions
+- **Episodic indexing** — structured event extraction for temporal and aggregation queries
+- **Contrastive pairs & heuristic distillation** — learning from what worked vs. what failed
+
+These are surfaced through `context()` and `checkpoint()` automatically when enabled.
+
 ---
 
 ## Architecture
@@ -317,7 +338,7 @@ m.think("complex question requiring reasoning across memories")
 ```bash
 pip install dhee[openai,mcp]     # OpenAI (recommended, cheapest embeddings)
 pip install dhee[gemini,mcp]     # Google Gemini
-pip install dhee[ollama,mcp]     # Ollama (local, zero cost)
+pip install dhee[ollama,mcp]     # Ollama (local inference, no API costs)
 ```
 
 ---
@@ -334,7 +355,7 @@ pytest
 ---
 
 <p align="center">
-  <b>4 tools. 1 LLM call. Your agent remembers, learns, and predicts.</b>
+  <b>4 operations. Deferred enrichment. Your agent remembers, learns, and predicts.</b>
   <br><br>
   <a href="https://github.com/Sankhya-AI/Dhee">GitHub</a> &middot;
   <a href="https://pypi.org/project/dhee">PyPI</a> &middot;

{dhee-2.0.0 → dhee-3.0.0}/README.md

@@ -7,7 +7,7 @@
 <h3 align="center">The cognition layer that turns your agent into a HyperAgent.</h3>
 
 <p align="center">
-  4 tools. 1 LLM call per session. ~$0.004 total cost.<br>
+  4-operation API. Deferred enrichment. Minimal hot-path cost.<br>
   Your agent remembers, learns from outcomes, and predicts what you need next.
 </p>
 
@@ -33,9 +33,17 @@ Most memory layers are glorified vector stores. Store text, retrieve text. Your
 
 ### Benchmark: LongMemEval
 
-Dhee achieves near-perfect retrieval on [LongMemEval](https://arxiv.org/abs/2410.10813), the standard benchmark for long-term conversational memory — temporal reasoning, multi-session aggregation, knowledge updates, and counterfactual tracking across 500+ questions.
+Dhee is being evaluated on [LongMemEval](https://arxiv.org/abs/2410.10813), the standard benchmark for long-term conversational memory — temporal reasoning, multi-session aggregation, knowledge updates, and counterfactual tracking across 500+ questions. Preliminary results are promising.
 
-> Evaluation run in progress. Full results and methodology will be published in the benchmark report.
+> Full methodology and results will be published in the benchmark report.
+
+---
+
+## Status
+
+Dhee is **experimental software under active development**. The core 4-operation API (`remember`/`recall`/`context`/`checkpoint`) is stable. Advanced subsystems (belief tracking, policy extraction, episodic indexing) are functional but evolving.
+
+Use it. Build on it. But know that internals will change.
 
 ---
 
@@ -93,7 +101,7 @@ Every interface — MCP, Python, CLI, JS — exposes the same 4 operations.
 ### `remember(content)`
 Store a fact, preference, or observation.
 
-**Hot path**: 0 LLM calls, 1 embedding (~$0.0002). The memory is stored immediately. Echo enrichment (paraphrases, keywords, question-forms that make future recall dramatically better) is deferred to `checkpoint`.
+**Hot path**: 0 LLM calls, 1 embedding (~$0.0002 typical). The memory is stored immediately. Echo enrichment (paraphrases, keywords, question-forms that make future recall dramatically better) is deferred to `checkpoint`.
 
 ```python
 d.remember("User prefers FastAPI over Flask")
@@ -103,7 +111,7 @@ d.remember("Project uses PostgreSQL 15 with pgvector")
 ### `recall(query)`
 Search memory. Returns top-K results ranked by relevance.
 
-**Hot path**: 0 LLM calls, 1 embedding (~$0.0002). Pure vector search with echo-boosted re-ranking.
+**Hot path**: 0 LLM calls, 1 embedding (~$0.0002 typical). Pure vector search with echo-boosted re-ranking.
 
 ```python
 results = d.recall("what database does the project use?")
@@ -161,6 +169,8 @@ d.checkpoint(
 | `checkpoint` | 1 per ~10 memories | 0 | ~$0.001 |
 | **Typical session** | **1** | **~15** | **~$0.004** |
 
+> Costs assume OpenAI `text-embedding-3-small` at current pricing. Actual costs vary by provider, model, and configuration.
+
 ---
 
 ## How It Works (Under the Hood)
@@ -178,7 +188,7 @@ Stores memories in SQLite + a vector index. On the hot path (`remember`/`recall`
 
 All of this happens in **1 LLM call per ~10 memories**. Not 4 calls per memory. One batched call.
 
-Memory decays naturally (Ebbinghaus curve). Frequently accessed memories get promoted from short-term to long-term. Unused ones fade. ~45% less storage than systems that keep everything forever.
+Memory decays naturally (Ebbinghaus curve). Frequently accessed memories get promoted from short-term to long-term. Unused ones fade. Storage naturally reduces over time as unused memories decay, unlike systems that keep everything indefinitely.
 
 ### Cognition Engine — Buddhi
 
@@ -193,6 +203,17 @@ Zero LLM calls on the hot path. Pure pattern matching + statistics. Persistence
 
 Inspired by [Meta's DGM-Hyperagents](https://arxiv.org/abs/2603.19461) — agents that emergently develop persistent memory and performance tracking achieve self-accelerating improvement that transfers across domains. Dhee provides these capabilities as infrastructure.
 
+#### Experimental Extensions
+
+Beyond the core cognition engine, Dhee includes experimental subsystems that are functional but still evolving:
+
+- **Belief store** — confidence-tracked facts with Bayesian updates and contradiction detection
+- **Policy store** — outcome-linked condition→action rules extracted from task completions
+- **Episodic indexing** — structured event extraction for temporal and aggregation queries
+- **Contrastive pairs & heuristic distillation** — learning from what worked vs. what failed
+
+These are surfaced through `context()` and `checkpoint()` automatically when enabled.
+
 ---
 
 ## Architecture
@@ -245,7 +266,7 @@ m.think("complex question requiring reasoning across memories")
 ```bash
 pip install dhee[openai,mcp]     # OpenAI (recommended, cheapest embeddings)
 pip install dhee[gemini,mcp]     # Google Gemini
-pip install dhee[ollama,mcp]     # Ollama (local, zero cost)
+pip install dhee[ollama,mcp]     # Ollama (local inference, no API costs)
 ```
 
 ---
@@ -262,7 +283,7 @@ pytest
 ---
 
 <p align="center">
-  <b>4 tools. 1 LLM call. Your agent remembers, learns, and predicts.</b>
+  <b>4 operations. Deferred enrichment. Your agent remembers, learns, and predicts.</b>
   <br><br>
   <a href="https://github.com/Sankhya-AI/Dhee">GitHub</a> &middot;
   <a href="https://pypi.org/project/dhee">PyPI</a> &middot;

{dhee-2.0.0 → dhee-3.0.0}/dhee/__init__.py

@@ -1,29 +1,28 @@
-"""dhee — Cognition as a Service. The memory layer that makes ANY agent intelligent.
+"""dhee — The cognition layer that turns any agent into a HyperAgent.
 
-- FadeMem: Dual-layer (SML/LML) with natural decay
-- EchoMem: Multi-modal encoding for stronger retention
-- CategoryMem: Dynamic hierarchical category organization
-- Universal Engram: Structured facts + context anchoring
-- Cognition Engine: Memory-grounded recursive reasoning
-- Prospective Scenes: Memory-driven future anticipation
+4 operations. Deferred enrichment. Minimal hot-path cost.
+Your agent remembers, learns from outcomes, and predicts what you need next.
 
-Quick Start (zero-config, no API key):
-    from dhee import Memory
-    m = Memory()
-    m.add("User prefers Python")
-    results = m.search("programming preferences")
+Quick Start:
+    from dhee import Dhee
 
-Tiered Memory Classes:
+    d = Dhee()
+    d.remember("User prefers dark mode")
+    d.recall("what theme does the user like?")
+    d.context("fixing auth bug")
+    d.checkpoint("Fixed it", what_worked="git blame first")
+
+Memory Classes:
     CoreMemory   — lightweight: add/search/delete + decay (no LLM)
     SmartMemory  — + echo encoding, categories, knowledge graph (needs LLM)
-    FullMemory   — + scenes, profiles, tasks, cognition (everything)
+    FullMemory   — + scenes, profiles, orchestration, cognition (everything)
     Memory       — alias for CoreMemory (lightest default)
 """
 
 from dhee.memory.core import CoreMemory
 from dhee.memory.smart import SmartMemory
 from dhee.memory.main import FullMemory
-from dhee.simple import Engram, Dhee
+from dhee.simple import Dhee
 from dhee.adapters.base import DheePlugin
 from dhee.core.category import CategoryProcessor, Category, CategoryType, CategoryMatch
 from dhee.core.echo import EchoProcessor, EchoDepth, EchoResult
@@ -32,16 +31,15 @@ from dhee.configs.base import MemoryConfig, FadeMemConfig, EchoMemConfig, Catego
 # Default: CoreMemory (lightest, zero-config)
 Memory = CoreMemory
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 __all__ = [
-    # Tiered memory classes
+    # Memory classes
     "CoreMemory",
     "SmartMemory",
     "FullMemory",
     "Memory",
-    # Simplified interface
+    # Simplified interface (the 4-operation API)
     "Dhee",
-    "Engram",
     # Universal plugin
     "DheePlugin",
     # CategoryMem
@@ -60,9 +58,3 @@ __all__ = [
     "CategoryMemConfig",
     "ScopeConfig",
 ]
-
-
-def _load_teaching():
-    """Lazy-load teaching module to avoid import overhead when not needed."""
-    from dhee.teaching import ConceptStore, StudentModel, TeachingMemory, TeachingConfig
-    return ConceptStore, StudentModel, TeachingMemory, TeachingConfig