Merge pull request #11 from Sankhya-AI/alpha

feat: Dhee V2.0 — Self-Evolving Cognition Plugin

Author: Ashish-dwi99

CHANGELOG.md

@@ -4,6 +4,91 @@ 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.0.0] - 2026-03-30
+
+Dhee V2: Self-Evolving Cognition Plugin. This release transforms Dhee from a memory layer into a **self-improving cognition plugin** that can make any agent — local or cloud, software or embodied — a HyperAgent that gets better with every interaction.
+
+### Added — Phase 1: Universal Plugin
+
+- **DheePlugin** (`dhee/adapters/base.py`): Framework-agnostic entry point wrapping Engram + Buddhi behind 4 tools (remember/recall/context/checkpoint), with session lifecycle (frozen snapshot pattern) and trajectory recording for skill mining.
+- **DheeEdge** (`dhee/edge/`): Minimal-footprint offline plugin for hardware/humanoid deployment. All-local inference (GGUF + ONNX), embodiment hooks (`on_sensor_input`, `on_action_result`, `predict_environment`), <500MB working set.
+- **BuddhiMini** (`dhee/mini/`): Scaffold for trainable model with 3 new task heads (`[MEMORY_OP]`, `[HEURISTIC]`, `[RETRIEVAL_JUDGE]`) on top of DheeModel. Includes `TraceSegmenter` that splits agent trajectories into `[REASON]/[ACT]/[MEMORY_OP]` spans for structured training data.
+- Export `DheePlugin` from `dhee.__init__` and `dhee/adapters/__init__`.
+- `pyproject.toml`: Added `edge` optional dependency group.
+- `SamskaraCollector.get_training_data()`: Exports SFT samples, DPO pairs, and vasana reports for the training pipeline.
+- `DheeLLM`: 3 new convenience methods (`classify_memory_op`, `generate_heuristic`, `judge_retrieval`).
+
+### Added — Phase 2: Self-Evolving Cognition
+
+- **ContrastiveStore** (`dhee/core/contrastive.py`): Success/failure pair storage with MaTTS re-ranking. Inspired by *ReasoningBank* (arXiv:2509.25140). Auto-creates pairs from `checkpoint(what_worked=..., what_failed=...)`. Exports DPO training pairs.
+- **HeuristicDistiller** (`dhee/core/heuristic.py`): Distills abstract reasoning patterns at 3 levels (specific / domain / universal) from agent trajectories. Inspired by *ERL: Efficient Reinforcement Learning* (arXiv:2603.24639). Deduplicates via Jaccard similarity.
+- **MetaBuddhi** (`dhee/core/meta_buddhi.py`): Self-referential cognition loop — proposes retrieval strategy mutations, evaluates them against samskara signals, promotes or rolls back. Inspired by *DGM-Hyperagents* (arXiv:2603.19461). The improvement procedure can improve itself.
+- **RetrievalStrategy** (`dhee/core/strategy.py`): Versioned scoring weights stored as human-readable JSON files. Tunable knobs: semantic/keyword weights, recency boost, contrastive boost, heuristic relevance, context budgets.
+- **ProgressiveTrainer** (`dhee/mini/progressive_trainer.py`): 3-stage training pipeline (SFT → DPO → RL gate). Inspired by *AgeMem* (arXiv:2601.01885). Weights samples by vasana degradation signals. Minimum thresholds prevent training on insufficient data.
+- **HyperContext** gains `contrasts` and `heuristics` fields — agents now receive contrastive evidence (do/avoid) and learned heuristics at session start.
+- **Buddhi** auto-wiring: `reflect()` auto-creates contrastive pairs and distills heuristics. `get_hyper_context()` populates contrasts and heuristics.
+- **HybridSearcher**: Added `contrastive_boost` parameter — results aligned with past successes score higher.
+- **EvolutionLayer**: Now runs dual loops — Nididhyasana (model training) + MetaBuddhi (strategy improvement).
+- **SkillMiner**: Triggers heuristic distillation after successful skill mining.
+
+### Added — Phase 3: Scale
+
+- **EvolvingGraph** (`dhee/core/graph_evolution.py`): Extends KnowledgeGraph with entity versioning (append-only JSONL), personalized PageRank per user/agent, and schema-free entity extraction via LLM (entities are typed as `DYNAMIC` when they don't match the fixed schema).
+- **HiveMemory** (`dhee/hive/hive_memory.py`): Multi-agent shared cognition on top of engram-bus. Agents publish insights, heuristics, and skills to the hive. Quality gating via Wilson score lower bound. Voting and adoption tracking.
+- **CRDT Sync** (`dhee/hive/sync.py`): Offline/edge sync protocol. LWW-Register for content, G-Counter for votes, OR-Set for adoption lists. `SyncEnvelope` wire format (JSON over bytes). Nodes converge after arbitrary offline periods.
+- **Framework Adapters**:
+  - `dhee/adapters/openai_funcs.py` — `OpenAIToolAdapter` with `tool_definitions()` and `execute()` dispatch. Works with any API-compatible provider.
+  - `dhee/adapters/langchain.py` — `get_dhee_tools()` returns 4 LangChain `BaseTool` instances. Lazy import — no hard dependency.
+  - `dhee/adapters/autogen.py` — `get_autogen_functions()` for v0.2, `get_autogen_tool_specs()` for v0.4+. `register_dhee_tools()` for auto-registration.
+  - `dhee/adapters/system_prompt.py` — `generate_snapshot()` renders HyperContext as a frozen system prompt block. Configurable sections, minimal mode for edge.
+- **EdgeTrainer** (`dhee/edge/edge_trainer.py`): On-device micro-training. LoRA rank-4, CPU-only, <2GB RAM. Deferred training mode for GGUF models. Vasana-weighted sample emphasis.
+- **KnowledgeGraph**: Added `DYNAMIC` entity type, `save()`/`load()` JSON persistence.
+
+### Changed
+
+- **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.
+
+### Research References
+
+This release was informed by the following research (March 2026):
+
+| Paper | Key Idea Applied |
+|-------|-----------------|
+| *DGM-Hyperagents* (arXiv:2603.19461) | Self-referential meta-agents that modify their own improvement procedure → MetaBuddhi |
+| *ERL* (arXiv:2603.24639) | Distill trajectories into abstract heuristics, not raw logs → HeuristicDistiller |
+| *ReasoningBank* (arXiv:2509.25140) | Contrastive learning from success/failure pairs, MaTTS scoring → ContrastiveStore |
+| *AgeMem* (arXiv:2601.01885) | Memory ops as RL-optimized tool calls, 3-stage progressive training → ProgressiveTrainer |
+| *Structured Agent Distillation* (arXiv:2505.13820) | [REASON]/[ACT] segmented traces for training small models → TraceSegmenter |
+
+### Migration from V1
+
+V2 is backwards-compatible with V1. Existing code using `Memory`, `Engram`, or `Dhee` classes continues to work unchanged. The new `DheePlugin` is additive — adopt it when you want the self-evolution capabilities.
+
+```python
+# V1 (still works)
+from dhee import Memory
+m = Memory()
+m.add("fact")
+
+# V2 (new universal plugin)
+from dhee import DheePlugin
+p = DheePlugin()
+p.remember("fact")
+ctx = p.context("what am I working on?")
+prompt = p.session_start("fixing auth bug")
+```
+
+---
+
+## [1.0.0] - 2026-03-22
+
+### Changed
+- Renamed project from Engram to Dhee.
+- Clean repository for public push.
+- All imports updated (`engram.*` → `dhee.*`).
+
 ## [0.4.0] - 2025-02-09
 
 ### Added

dhee/__init__.py

@@ -23,23 +23,27 @@
 from dhee.memory.core import CoreMemory
 from dhee.memory.smart import SmartMemory
 from dhee.memory.main import FullMemory
-from dhee.simple import Engram
+from dhee.simple import Engram, 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
 
 # Default: CoreMemory (lightest, zero-config)
 Memory = CoreMemory
 
-__version__ = "1.0.0"
+__version__ = "2.0.0"
 __all__ = [
     # Tiered memory classes
     "CoreMemory",
     "SmartMemory",
     "FullMemory",
     "Memory",
     # Simplified interface
+    "Dhee",
     "Engram",
+    # Universal plugin
+    "DheePlugin",
     # CategoryMem
     "CategoryProcessor",
     "Category",

dhee/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Dhee adapters — universal plugin interface for any agent framework.
+
+Available adapters:
+  - DheePlugin: Base universal plugin (remember/recall/context/checkpoint)
+  - OpenAIToolAdapter: OpenAI function calling (tools= parameter)
+  - get_dhee_tools: LangChain BaseTool wrappers
+  - get_autogen_functions: AutoGen v0.2 callables + schemas
+  - generate_snapshot: Frozen system prompt for non-tool-calling agents
+"""
+
+from dhee.adapters.base import DheePlugin
+
+__all__ = ["DheePlugin"]