Merge pull request #14 from Sankhya-AI/alpha

V2.2.1

Author: Ashish-dwi99

CHANGELOG.md

@@ -4,27 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [2.1.0] - 2026-03-30 — Production Cognition
+## [2.1.0] - 2026-03-30 — Cognition Primitives
 
-Dhee V2.1: All 10 cognition capabilities at production A-grade. Every self-improvement loop is closed and verified with 60 tests.
+Dhee V2.1: Adds first-class cognitive primitives (episodes, tasks, policies, beliefs, triggers) and a 60-test suite that exercises them. These are internal building blocks — the public API remains the 4-operation surface (remember/recall/context/checkpoint).
 
-### Added — Production Cognition Systems
+### Added — Cognitive Primitives (internal, importable from `dhee.core`)
 
-- **Episode System** (`dhee/core/episode.py`): First-class temporal unit of agent experience. Lifecycle: open→active→closed→archived→forgotten. Automatic boundary detection via time gap (>30min) and topic shift (Jaccard <20%). Utility-based selective forgetting with exponential recency decay (7-day half-life), access frequency, outcome value, and connection density scoring. Hard cap at 500 episodes/user.
-- **Task State** (`dhee/core/task_state.py`): Structured task tracking with goal/plan/progress/blockers/outcome. Full lifecycle: created→in_progress→blocked→completed/failed. Step-level tracking with `advance_step()`. Blocker management (soft/hard severity). Plan success rate analysis for policy learning.
-- **Policy Cases** (`dhee/core/policy.py`): Outcome-linked condition→action rules (not text reflections). Wilson score confidence at 95% interval. Laplace-smoothed win rate. Auto-promotion to VALIDATED (confidence≥0.5, win_rate≥0.6) and auto-deprecation (apply≥5, win_rate<0.4). Policy extraction from completed task patterns.
-- **Belief Tracking** (`dhee/core/belief.py`): Bayesian-inspired confidence updates (lr=0.15×evidence_strength). Contradiction detection via keyword Jaccard overlap >0.4 + negation patterns. Revision history with stability metric. Status lifecycle: proposed→held→challenged→revised|retracted. Auto-creation from factual assertions in stored memories.
-- **Trigger System** (`dhee/core/trigger.py`): 5 trigger types all returning `TriggerResult(fired, confidence, reason)`. Keyword (overlap scoring + required keywords), Time (after/before/recurring/window modes), Event (type + regex pattern), Composite (AND/OR/NOT with min/max confidence), Sequence (ordered events within time window, tightness-based confidence). Backwards-compatible bridge from legacy Intention format.
-- **Test Suite** (`tests/test_cognition_v3.py`): 60 tests across 10 classes covering all capabilities + full pipeline integration.
+- **Episode System** (`dhee/core/episode.py`): Temporal unit of agent experience. Lifecycle: open→active→closed→archived→forgotten. Boundary detection via time gap and topic shift. Utility-based selective forgetting. JSON-file-backed persistence (suitable for local-first use; production systems should own their own persistence).
+- **Task State** (`dhee/core/task_state.py`): Structured task tracking with goal/plan/progress/blockers/outcome. Step-level tracking. Blocker management. Plan success rate analysis.
+- **Policy Cases** (`dhee/core/policy.py`): Outcome-linked condition→action rules with Wilson score confidence. Auto-promotion and auto-deprecation based on win rate.
+- **Belief Tracking** (`dhee/core/belief.py`): Confidence updates with evidence tracking. Contradiction detection via keyword overlap + negation patterns. Revision history.
+- **Trigger System** (`dhee/core/trigger.py`): 5 trigger types (keyword, time, event, composite, sequence) returning `TriggerResult(fired, confidence, reason)`. Backwards-compatible bridge from legacy intentions.
+- **Test Suite** (`tests/test_cognition_v3.py`): 60 tests covering cognition primitives, contrastive pairs, heuristic distillation, meta-learning, and Buddhi pipeline wiring.
 
-### Changed — Closed Self-Improvement Loops
+### Changed
 
-- **Contrastive Pairs**: Upgraded from scaffolded to production. Retrieval-time integration in HyperContext, MaTTS scoring, DPO export for training.
-- **Heuristic Distillation**: Upgraded from scaffolded to production. Outcome validation loop closed — `reflect()` validates heuristics used in the session and updates confidence.
-- **Meta-Learning Gate**: Upgraded from scaffolded to production. Real evaluation via propose/evaluate/promote/rollback cycle verified.
-- **Progressive Training**: Upgraded from theoretical to production. Real data flow from Samskara → SFT → DPO → RL pipeline.
-- **Buddhi** (`dhee/core/buddhi.py`): HyperContext expanded with `episodes`, `task_states`, `policies`, `beliefs`. `reflect()` now creates contrastive pairs + distills heuristics + validates used heuristics + extracts policies + updates beliefs. `on_memory_stored()` auto-creates beliefs for factual assertions.
-- **DheePlugin** (`dhee/adapters/base.py`): `checkpoint()` handles episode closure, task state lifecycle, selective forgetting. System prompt renderer includes Proven Strategies, Established Beliefs, Active Tasks, Recent Experience. New convenience methods: `add_belief()`, `challenge_belief()`, `create_task()`, `advance_task()`.
+- **Buddhi**: HyperContext expanded with episodes, task_states, policies, beliefs. `reflect()` creates contrastive pairs, distills heuristics, extracts policies, updates beliefs.
+- **DheePlugin**: `checkpoint()` handles episode closure and task lifecycle. System prompt renderer includes strategies, beliefs, tasks, experience.
 - **Version**: 2.0.0 → 2.1.0
 
 ---
@@ -73,7 +69,7 @@ Dhee V2: Self-Evolving Cognition Plugin. This release transforms Dhee from a mem
 
 - **Version**: 1.0.0 → 2.0.0
 - **MCP server** (`dhee/mcp_slim.py`): Refactored to wrap `DheePlugin` as backing singleton.
-- **pyproject.toml**: Updated description, keywords, classifier to Production/Stable.
+- **pyproject.toml**: Updated description, keywords, classifiers.
 
 ### Research References
 

dhee/__init__.py

@@ -1,52 +1,45 @@
-"""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
 from dhee.configs.base import MemoryConfig, FadeMemConfig, EchoMemConfig, CategoryMemConfig, ScopeConfig
-from dhee.core.belief import BeliefNode, BeliefStore, BeliefStatus
-from dhee.core.policy import PolicyCase, PolicyStore, PolicyStatus
-from dhee.core.task_state import TaskState, TaskStateStore, TaskStatus
-from dhee.core.episode import Episode, EpisodeStore, EpisodeStatus
-from dhee.core.trigger import TriggerManager, TriggerResult, TriggerContext
 
 # Default: CoreMemory (lightest, zero-config)
 Memory = CoreMemory
 
 __version__ = "2.2.0b1"
 __all__ = [
-    # Tiered memory classes
+    # Memory classes
     "CoreMemory",
     "SmartMemory",
     "FullMemory",
     "Memory",
-    # Simplified interface
+    # Simplified interface (the 4-operation API)
     "Dhee",
-    "Engram",
     # Universal plugin
     "DheePlugin",
     # CategoryMem
@@ -64,26 +57,4 @@
     "EchoMemConfig",
     "CategoryMemConfig",
     "ScopeConfig",
-    # Cognitive subsystems
-    "BeliefNode",
-    "BeliefStore",
-    "BeliefStatus",
-    "PolicyCase",
-    "PolicyStore",
-    "PolicyStatus",
-    "TaskState",
-    "TaskStateStore",
-    "TaskStatus",
-    "Episode",
-    "EpisodeStore",
-    "EpisodeStatus",
-    "TriggerManager",
-    "TriggerResult",
-    "TriggerContext",
 ]
-
-
-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

dhee/benchmarks/arc_agi.py

@@ -206,7 +206,7 @@ def run_arc_benchmark(args: argparse.Namespace) -> Dict[str, Any]:
     memory = None
     if args.mode == "memory":
         from dhee.configs.base import MemoryConfig
-        from dhee.memory.main import Memory
+        from dhee.memory.main import FullMemory
 
         tmpdir = tempfile.mkdtemp(prefix="arc_bench_")
         config = MemoryConfig(
@@ -221,7 +221,7 @@ def run_arc_benchmark(args: argparse.Namespace) -> Dict[str, Any]:
             scene={"enable_scenes": False},
             profile={"enable_profiles": False},
         )
-        memory = Memory(config)
+        memory = FullMemory(config)
         print(f"Embedder: {args.embedder_provider}/{args.embedder_model}")
         print(f"Memory DB: {tmpdir}")
         print()

dhee/cli.py

@@ -1,16 +1,16 @@
-"""engram CLI — memory layer for AI agents.
+"""dhee CLI — cognition layer for AI agents.
 
 Usage:
-    engram setup              Interactive setup wizard
-    engram add "text"         Add a memory
-    engram search "query"     Search memories
-    engram list               List all memories
-    engram stats              Memory statistics
-    engram decay              Apply forgetting
-    engram categories         List categories
-    engram export             Export to JSON
-    engram import <file>      Import from JSON
-    engram status             Version, config, DB info
+    dhee setup              Interactive setup wizard
+    dhee add "text"         Add a memory
+    dhee search "query"     Search memories
+    dhee list               List all memories
+    dhee stats              Memory statistics
+    dhee decay              Apply forgetting
+    dhee categories         List categories
+    dhee export             Export to JSON
+    dhee import <file>      Import from JSON
+    dhee status             Version, config, DB info
 """
 
 import argparse
@@ -323,7 +323,7 @@ def cmd_benchmark(args: argparse.Namespace) -> None:
     from dhee import Memory
 
     print("=" * 60)
-    print(" engram benchmark")
+    print(" dhee benchmark")
     print("=" * 60)
 
     # Cold start

dhee/cli_config.py

@@ -84,7 +84,7 @@ def get_api_key(provider: str) -> Optional[str]:
 
 def get_memory_instance(config: Optional[Dict[str, Any]] = None):
     """Build a Memory instance from CLI config."""
-    from dhee.memory.main import Memory
+    from dhee.memory.main import FullMemory
     from dhee.configs.base import (
         MemoryConfig,
         VectorStoreConfig,
@@ -136,4 +136,4 @@ def get_memory_instance(config: Optional[Dict[str, Any]] = None):
         engram=FadeMemConfig(enable_forgetting=True),
     )
 
-    return Memory(memory_config)
+    return FullMemory(memory_config)

dhee/configs/base.py

@@ -460,7 +460,7 @@ class EngramExtractionConfig(BaseModel):
 class SkillConfig(BaseModel):
     """Configuration for the skill-learning agent memory system."""
     enable_skills: bool = True
-    skill_collection_name: str = "engram_skills"
+    skill_collection_name: str = "dhee_skills"
     min_confidence_for_auto_apply: float = 0.3
     enable_mining: bool = True
     min_trajectory_steps: int = 3

dhee/configs/presets.py

@@ -38,12 +38,12 @@ def minimal_config():
         vector_store=VectorStoreConfig(
             provider="memory",
             config={
-                "collection_name": "engram_memories",
+                "collection_name": "dhee_memories",
                 "embedding_model_dims": 384,
             },
         ),
         history_db_path=os.path.join(data_dir, "history.db"),
-        collection_name="engram_memories",
+        collection_name="dhee_memories",
         embedding_model_dims=384,
         engram=FadeMemConfig(enable_forgetting=True),
         echo=EchoMemConfig(enable_echo=False),
@@ -99,15 +99,15 @@ def smart_config():
             provider="zvec",
             config={
                 "path": os.path.join(data_dir, "zvec"),
-                "collection_name": "engram_memories",
+                "collection_name": "dhee_memories",
                 "embedding_model_dims": dims,
             },
         )
     else:
         vs = VectorStoreConfig(
             provider="memory",
             config={
-                "collection_name": "engram_memories",
+                "collection_name": "dhee_memories",
                 "embedding_model_dims": dims,
             },
         )
@@ -120,7 +120,7 @@ def smart_config():
         llm=LLMConfig(provider=llm_provider, config={}),
         vector_store=vs,
         history_db_path=os.path.join(data_dir, "history.db"),
-        collection_name="engram_memories",
+        collection_name="dhee_memories",
         embedding_model_dims=dims,
         engram=FadeMemConfig(enable_forgetting=True),
         echo=EchoMemConfig(enable_echo=has_llm),

dhee/core/__init__.py

@@ -4,71 +4,19 @@
 from dhee.core.fusion import fuse_memories
 from dhee.core.retrieval import composite_score
 from dhee.core.category import CategoryProcessor, Category, CategoryMatch, CategoryType
-from dhee.core.belief import BeliefNode, BeliefStore, BeliefStatus, Evidence, BeliefRevision
-from dhee.core.policy import PolicyCase, PolicyStore, PolicyStatus, PolicyCondition, PolicyAction
-from dhee.core.task_state import TaskState, TaskStateStore, TaskStatus, TaskStep, Blocker
-from dhee.core.episode import Episode, EpisodeStore, EpisodeStatus, EpisodeEvent
-from dhee.core.trigger import (
-    TriggerManager,
-    KeywordTrigger,
-    TimeTrigger,
-    EventTrigger,
-    CompositeTrigger,
-    SequenceTrigger,
-    TriggerResult,
-    TriggerContext,
-)
 
 __all__ = [
-    # Decay
     "calculate_decayed_strength",
     "should_forget",
     "should_promote",
-    # Conflict
     "resolve_conflict",
-    # Echo
     "EchoProcessor",
     "EchoDepth",
     "EchoResult",
-    # Fusion
     "fuse_memories",
-    # Retrieval
     "composite_score",
-    # Category
     "CategoryProcessor",
     "Category",
     "CategoryMatch",
     "CategoryType",
-    # Belief
-    "BeliefNode",
-    "BeliefStore",
-    "BeliefStatus",
-    "Evidence",
-    "BeliefRevision",
-    # Policy
-    "PolicyCase",
-    "PolicyStore",
-    "PolicyStatus",
-    "PolicyCondition",
-    "PolicyAction",
-    # Task State
-    "TaskState",
-    "TaskStateStore",
-    "TaskStatus",
-    "TaskStep",
-    "Blocker",
-    # Episode
-    "Episode",
-    "EpisodeStore",
-    "EpisodeStatus",
-    "EpisodeEvent",
-    # Trigger
-    "TriggerManager",
-    "KeywordTrigger",
-    "TimeTrigger",
-    "EventTrigger",
-    "CompositeTrigger",
-    "SequenceTrigger",
-    "TriggerResult",
-    "TriggerContext",
 ]

dhee/core/consolidation.py

@@ -14,7 +14,7 @@
 from dhee.core.active_memory import ActiveMemoryStore
 
 if TYPE_CHECKING:
-    from dhee.memory.main import Memory
+    from dhee.memory.main import FullMemory
 
 logger = logging.getLogger(__name__)
 
@@ -25,7 +25,7 @@ class ConsolidationEngine:
     def __init__(
         self,
         active_store: ActiveMemoryStore,
-        memory: "Memory",
+        memory: "FullMemory",
         config: ActiveMemoryConfig,
     ):
         self.active = active_store