hipcortex 0.5.2__tar.gz → 1.4.0__tar.gz

{hipcortex-0.5.2 → hipcortex-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hipcortex
-Version: 0.5.2
+Version: 1.4.0
 Summary: Persistent causal memory for AI agents -- LangChain, LlamaIndex, AutoGen, CrewAI
 Author: HipCortex Contributors
 License: Apache-2.0
@@ -59,7 +59,7 @@ hipcortex install  # wizard: MCP hosts + copies ~/.hipcortex-mcp/server.py (18 t
 hipcortex channels # honesty matrix (native / mcp / framework / guide)
 ```
 
-**Version matrix:** product pip/Cargo/MCP `serverInfo` = **0.5.2**; VS Code VSIX = **0.5.7** ([release](https://github.com/farmountain/HipCortex/releases/download/v0.5.7/hipcortex-memory-0.5.7.vsix)). See [docs/channels.md](../../docs/channels.md).
+**Version matrix:** product pip/Cargo/MCP `serverInfo` = **0.5.2**; VS Code VSIX = **0.5.8**. See [docs/channels.md](../../docs/channels.md).
 
 ---
 

{hipcortex-0.5.2 → hipcortex-1.4.0}/README.md

@@ -1,122 +1,122 @@
-# HipCortex Python SDK (`v0.5.2`)
-
-**Persistent causal topological memory, recursive Bayesian world-model prediction (`/worldmodel/rollout`), and automatic FSM skill compilation for autonomous AI agents.**
-
-Runs against the standalone local Rust binary (`http://127.0.0.1:3030`) with `0.48–0.61 ms p50` write latency, SHA-256 Merkle audit chains, and Headroom context budgeting (`59–88% token savings`).
-
----
-
-## 🚀 Installation
-
-```bash
-pip install hipcortex
-hipcortex doctor   # verify server health + version after install
-hipcortex install  # wizard: MCP hosts + copies ~/.hipcortex-mcp/server.py (18 tools)
-hipcortex channels # honesty matrix (native / mcp / framework / guide)
-```
-
-**Version matrix:** product pip/Cargo/MCP `serverInfo` = **0.5.2**; VS Code VSIX = **0.5.7** ([release](https://github.com/farmountain/HipCortex/releases/download/v0.5.7/hipcortex-memory-0.5.7.vsix)). See [docs/channels.md](../../docs/channels.md).
-
----
-
-## ⚡ Quick Start: Multi-Tier Memory & World Model Prediction
-
-```python
-from hipcortex import HipCortexClient
-
-client = HipCortexClient(base_url="http://127.0.0.1:3030")
-
-# 1. Multi-Tier Memory Ingestion (5 verified memory tiers)
-client.add_memory(
-    actor="agent",
-    action="configured",
-    target="jwt_token_ttl=3600",
-    record_type="Working",  # Mapped natively to Temporal tier
-    priority="high"
-)
-
-client.add_memory(
-    actor="agent",
-    action="established",
-    target="All database migrations must run inside transactions",
-    record_type="Semantic", # Mapped natively to Symbolic/LongTerm tier
-    priority="pinned"
-)
-
-# 2. Check SelfModel Execution Capacity Gates before running risky actions
-if client.can_execute("rollout"):
-    print("Health check passed — engine ready for simulation")
-
-# 3. World Model Trajectory Rollout Prediction (POST /worldmodel/rollout)
-rollout_result = client.rollout(
-    initial_state={"db_status": "locked", "active_tx": 1},
-    actions=["rollback_tx", "release_lock", "retry_migration"]
-)
-print("Predicted outcome:", rollout_result)
-```
-
----
-
-## 🧠 Proactive CodeAct Harness & Live Beliefs
-
-For autonomous agent harnesses (`LangChain`, `LlamaIndex`, `CrewAI`, `AutoGen`), query the topological substrate before reasoning:
-
-```python
-# Query live causal beliefs and Top-K topological context (Personalized PageRank)
-context = client.context(query="database migrations", actor="agent", limit=5)
-print("Active Topological Context:\n", context)
-
-# Store multi-hop reasoning or CoT reflection
-client.add_memory(
-    actor="agent",
-    action="reflected",
-    target="Migration failed due to missing index on users.email",
-    record_type="Causal"
-)
-```
-
----
-
-## 🧩 Framework Integrations
-
-### LangChain (`ConversationBufferMemory` drop-in)
-```python
-from hipcortex.langchain_memory import HipCortexMemory
-
-memory = HipCortexMemory(session_id="session-42", url="http://127.0.0.1:3030")
-```
-
-### LlamaIndex (`ChatStore`)
-```python
-from hipcortex.llamaindex_storage import HipCortexStorageContext
-
-storage_context = HipCortexStorageContext.from_defaults(client=client)
-```
-
-### CrewAI (`Remember` & `Recall` Tools)
-```python
-from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
-
-tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
-```
-
-### AutoGen (`Memory` Hook)
-```python
-from hipcortex.adapters.autogen import HipCortexAutoGenMemory
-
-mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
-agent.register_hook("process_message_before_send", mem.on_message_sent)
-```
-
----
-
-## 📊 Server Statistics & GDPR Right-to-Forget
-
-```python
-# Get Merkle hash chain status and tier counts
-stats = client.stats()
-print("Memory statistics:", stats)
-
-# Erase all records for a specific actor (GDPR compliant)
-client.forget("agent")
-```
+# HipCortex Python SDK (`v0.5.2`)
+
+**Persistent causal topological memory, recursive Bayesian world-model prediction (`/worldmodel/rollout`), and automatic FSM skill compilation for autonomous AI agents.**
+
+Runs against the standalone local Rust binary (`http://127.0.0.1:3030`) with `0.48–0.61 ms p50` write latency, SHA-256 Merkle audit chains, and Headroom context budgeting (`59–88% token savings`).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install hipcortex
+hipcortex doctor   # verify server health + version after install
+hipcortex install  # wizard: MCP hosts + copies ~/.hipcortex-mcp/server.py (18 tools)
+hipcortex channels # honesty matrix (native / mcp / framework / guide)
+```
+
+**Version matrix:** product pip/Cargo/MCP `serverInfo` = **0.5.2**; VS Code VSIX = **0.5.8**. See [docs/channels.md](../../docs/channels.md).
+
+---
+
+## ⚡ Quick Start: Multi-Tier Memory & World Model Prediction
+
+```python
+from hipcortex import HipCortexClient
+
+client = HipCortexClient(base_url="http://127.0.0.1:3030")
+
+# 1. Multi-Tier Memory Ingestion (5 verified memory tiers)
+client.add_memory(
+    actor="agent",
+    action="configured",
+    target="jwt_token_ttl=3600",
+    record_type="Working",  # Mapped natively to Temporal tier
+    priority="high"
+)
+
+client.add_memory(
+    actor="agent",
+    action="established",
+    target="All database migrations must run inside transactions",
+    record_type="Semantic", # Mapped natively to Symbolic/LongTerm tier
+    priority="pinned"
+)
+
+# 2. Check SelfModel Execution Capacity Gates before running risky actions
+if client.can_execute("rollout"):
+    print("Health check passed — engine ready for simulation")
+
+# 3. World Model Trajectory Rollout Prediction (POST /worldmodel/rollout)
+rollout_result = client.rollout(
+    initial_state={"db_status": "locked", "active_tx": 1},
+    actions=["rollback_tx", "release_lock", "retry_migration"]
+)
+print("Predicted outcome:", rollout_result)
+```
+
+---
+
+## 🧠 Proactive CodeAct Harness & Live Beliefs
+
+For autonomous agent harnesses (`LangChain`, `LlamaIndex`, `CrewAI`, `AutoGen`), query the topological substrate before reasoning:
+
+```python
+# Query live causal beliefs and Top-K topological context (Personalized PageRank)
+context = client.context(query="database migrations", actor="agent", limit=5)
+print("Active Topological Context:\n", context)
+
+# Store multi-hop reasoning or CoT reflection
+client.add_memory(
+    actor="agent",
+    action="reflected",
+    target="Migration failed due to missing index on users.email",
+    record_type="Causal"
+)
+```
+
+---
+
+## 🧩 Framework Integrations
+
+### LangChain (`ConversationBufferMemory` drop-in)
+```python
+from hipcortex.langchain_memory import HipCortexMemory
+
+memory = HipCortexMemory(session_id="session-42", url="http://127.0.0.1:3030")
+```
+
+### LlamaIndex (`ChatStore`)
+```python
+from hipcortex.llamaindex_storage import HipCortexStorageContext
+
+storage_context = HipCortexStorageContext.from_defaults(client=client)
+```
+
+### CrewAI (`Remember` & `Recall` Tools)
+```python
+from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
+
+tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
+```
+
+### AutoGen (`Memory` Hook)
+```python
+from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+
+mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+agent.register_hook("process_message_before_send", mem.on_message_sent)
+```
+
+---
+
+## 📊 Server Statistics & GDPR Right-to-Forget
+
+```python
+# Get Merkle hash chain status and tier counts
+stats = client.stats()
+print("Memory statistics:", stats)
+
+# Erase all records for a specific actor (GDPR compliant)
+client.forget("agent")
+```

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/__init__.py

@@ -1,15 +1,17 @@
-"""HipCortex Python SDK - AI memory engine client."""
-
-from .client import HipCortexClient
-from .async_client import AsyncHipCortexClient
-from .langchain_memory import HipCortexMemory, AsyncHipCortexMemory
-from .llamaindex_storage import HipCortexStorageContext
-
-__version__ = "0.5.2"
-__all__ = [
-    "HipCortexClient",
-    "AsyncHipCortexClient",
-    "HipCortexMemory",
-    "AsyncHipCortexMemory",
-    "HipCortexStorageContext",
-]
+"""HipCortex Python SDK - AI memory engine client."""
+
+from .client import HipCortexClient
+from .async_client import AsyncHipCortexClient
+from .langchain_memory import HipCortexMemory, AsyncHipCortexMemory
+from .llamaindex_storage import HipCortexStorageContext
+from .substrate import HipCortexSubstrate
+
+__version__ = "1.3.0"
+__all__ = [
+    "HipCortexClient",
+    "AsyncHipCortexClient",
+    "HipCortexMemory",
+    "AsyncHipCortexMemory",
+    "HipCortexStorageContext",
+    "HipCortexSubstrate",
+]

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/adapters/autogen.py

@@ -173,3 +173,57 @@ class HipCortexAutoGenMemory(Memory):  # type: ignore[misc]
 
     def forget_all(self) -> Dict[str, Any]:
         return self._client.forget(self._agent_id)
+
+
+class HipCortexAutoGenObserver:
+    """Passive AutoGen observer. Wire via agent hooks or v0.3 send/receive hooks."""
+
+    def __init__(self, client, actor: str = "autogen-agent"):
+        self._client = client
+        self._actor = actor
+
+    def _capture(self, action: str, target: str, record_type: str = "Temporal") -> None:
+        try:
+            self._client.add_memory(
+                actor=self._actor,
+                action=action,
+                target=target[:120],
+                record_type=record_type,
+                source="autogen-passive",
+            )
+        except Exception:
+            pass
+
+    def on_message_received(self, sender: str, content: str, role: str = "user") -> None:
+        self._capture("message_received", f"[{sender}/{role}] {str(content)[:100]}")
+
+    def on_message_sent(self, recipient: str, content: str) -> None:
+        self._capture("message_sent", f"[→{recipient}] {str(content)[:100]}")
+
+    def on_function_call(self, name: str, arguments: dict) -> None:
+        self._capture("function_call", f"{name}({str(arguments)[:80]})")
+
+    def on_function_result(self, name: str, result: str) -> None:
+        self._capture("function_result", f"{name} → {str(result)[:80]}")
+
+    def make_v03_send_hook(self):
+        """Hook for AutoGen v0.3 send hook."""
+        def _hook(message: dict) -> None:
+            try:
+                content = message.get("content", "") or ""
+                role = message.get("role", "unknown")
+                self._capture("message_sent", f"[{role}] {str(content)[:100]}")
+            except Exception:
+                pass
+        return _hook
+
+    def make_v03_receive_hook(self):
+        """Hook for AutoGen v0.3 receive hook."""
+        def _hook(message: dict, sender=None) -> None:
+            try:
+                content = message.get("content", "") or ""
+                sender_name = getattr(sender, "name", str(sender)) if sender else "unknown"
+                self._capture("message_received", f"[{sender_name}] {str(content)[:100]}")
+            except Exception:
+                pass
+        return _hook

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/adapters/crewai.py

@@ -171,3 +171,63 @@ def make_memory_tools(
         HipCortexRecallTool(client=client, agent_id=agent_id),
         HipCortexForgetTool(client=client, agent_id=agent_id),
     ]
+
+
+class HipCortexCrewObserver:
+    """Passive CrewAI observer. Wire via: Crew(step_callback=obs.step_callback, task_callback=obs.task_callback)."""
+
+    def __init__(self, client, actor: str = "crew-agent"):
+        self._client = client
+        self._actor = actor
+        self._injected: set = set()
+
+    def inject_context(self, crew) -> None:
+        """Inject relevant memories into crew context before kickoff. Idempotent."""
+        crew_id = id(crew)
+        if crew_id in self._injected:
+            return
+        self._injected.add(crew_id)
+        try:
+            memories = self._client.query_memory(actor=self._actor, limit=5)
+            if memories and hasattr(crew, "context"):
+                snippets = [f"[{m.get('action', '')}] {m.get('target', '')}" for m in memories]
+                prefix = "Prior context:\n" + "\n".join(snippets)
+                if isinstance(crew.context, str):
+                    crew.context = prefix + "\n\n" + crew.context
+        except Exception:
+            pass
+
+    @property
+    def step_callback(self):
+        """Callable for Crew(step_callback=...). Signature: fn(AgentAction) -> None."""
+        def _on_step(action) -> None:
+            try:
+                tool = getattr(action, "tool", "unknown")
+                tool_input = str(getattr(action, "tool_input", ""))[:80]
+                self._client.add_memory(
+                    actor=self._actor,
+                    action="crew_step",
+                    target=f"{tool}({tool_input})",
+                    record_type="Temporal",
+                    source="crewai-passive",
+                )
+            except Exception:
+                pass
+        return _on_step
+
+    @property
+    def task_callback(self):
+        """Callable for Task(callback=...). Signature: fn(TaskOutput) -> None."""
+        def _on_task(output) -> None:
+            try:
+                raw = getattr(output, "raw_output", None) or str(output)
+                self._client.add_memory(
+                    actor=self._actor,
+                    action="task_complete",
+                    target=str(raw)[:120],
+                    record_type="Reflexion",
+                    source="crewai-passive",
+                )
+            except Exception:
+                pass
+        return _on_task

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/cli.py

@@ -1380,7 +1380,7 @@ def _fallback_channels() -> list[dict]:
         {"id": "claude-code", "name": "Claude Code", "status": "native", "install": "hipcortex install"},
         {"id": "cursor", "name": "Cursor", "status": "mcp", "install": "hipcortex install"},
         {"id": "windsurf", "name": "Windsurf", "status": "mcp", "install": "hipcortex install"},
-        {"id": "vscode-extension", "name": "VS Code VSIX", "status": "native", "install": "hipcortex-memory-0.5.7.vsix"},
+        {"id": "vscode-extension", "name": "VS Code VSIX", "status": "native", "install": "hipcortex-memory-0.5.8.vsix"},
         {"id": "vscode-mcp", "name": "VS Code MCP", "status": "mcp", "install": "hipcortex install"},
         {"id": "cline", "name": "Cline", "status": "mcp", "install": "hipcortex install"},
         {"id": "roocode", "name": "RooCode", "status": "mcp", "install": "hipcortex install"},

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/client.py

@@ -10,6 +10,8 @@ import requests
 
 
 class HipCortexClient:
+    VERSION = "0.8.0"
+
     """Synchronous HTTP client for the HipCortex memory server.
 
     Args:
@@ -613,3 +615,158 @@ class HipCortexClient:
         resp.raise_for_status()
         return resp.json()
 
+    def get_state_diff(self, from_tx: int, to_tx: int) -> Dict[str, Any]:
+        """POST /v1/state/diff — causal StateDiff over a tx-log range."""
+        resp = self._session.post(
+            f"{self.base_url}/v1/state/diff",
+            json={"from_tx": from_tx, "to_tx": to_tx},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def consolidate_memory(self, min_group_size: int = 3) -> Dict[str, Any]:
+        """POST /v1/memory/consolidate — trigger hierarchical memory consolidation."""
+        resp = self._session.post(
+            f"{self.base_url}/v1/memory/consolidate",
+            json={"min_group_size": min_group_size},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_system_health(self) -> Dict[str, Any]:
+        """GET /self/health — SelfModel health + CalibrationTracker metrics."""
+        resp = self._session.get(f"{self.base_url}/self/health", timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_live_beliefs(
+        self,
+        actor: Optional[str] = None,
+        limit: int = 20,
+        min_conf: float = 0.0,
+    ) -> Dict[str, Any]:
+        """GET /memory/live_beliefs — filtered by actor and confidence threshold."""
+        params: Dict[str, Any] = {"limit": limit, "min_conf": min_conf}
+        if actor:
+            params["actor"] = actor
+        resp = self._session.get(
+            f"{self.base_url}/memory/live_beliefs", params=params, timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def simulate_rollout(
+        self,
+        initial_state: Any,
+        actions: List[str],
+        max_depth: int = 5,
+    ) -> Dict[str, Any]:
+        """POST /worldmodel/rollout — k-step (k≤5) Dirichlet-MAP world-model rollout."""
+        if not isinstance(initial_state, str):
+            initial_state = json.dumps(initial_state)
+        max_depth = min(max_depth, 5)
+        resp = self._session.post(
+            f"{self.base_url}/worldmodel/rollout",
+            json={"initial_state": initial_state, "actions": actions, "max_depth": max_depth},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Phase 5: Agent Surfaces (v0.8.0)
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        resp = self._session.get(f"{self.base_url}{path}", params=params, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post(self, path: str, body: Any = None) -> Dict[str, Any]:
+        resp = self._session.post(f"{self.base_url}{path}", json=body, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _delete(self, path: str) -> Dict[str, Any]:
+        resp = self._session.delete(f"{self.base_url}{path}", timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def transact(self, delta: Dict[str, Any], actor: str) -> Dict[str, Any]:
+        """POST /v1/cognitive/transact — apply a CognitiveDelta."""
+        return self._post("/v1/cognitive/transact", {"delta": delta, "actor": actor})
+
+    def cognitive_diff(self, from_tx: int, to_tx: int) -> Dict[str, Any]:
+        """GET /v1/cognitive/diff — causal StateDiff over a tx range."""
+        return self._get("/v1/cognitive/diff", params={"from_tx": from_tx, "to_tx": to_tx})
+
+    def self_health(self) -> Dict[str, Any]:
+        """GET /v1/self/health — SelfModel health metrics."""
+        return self._get("/v1/self/health")
+
+    def cognitive_snapshot(self, actor: str = "") -> Dict[str, Any]:
+        """GET /v1/cognitive/snapshot."""
+        return self._get("/v1/cognitive/snapshot", params={"actor": actor})
+
+    def fork_create(self) -> Dict[str, Any]:
+        """POST /v1/fork — create a new SimulationFork (CoW snapshot)."""
+        return self._post("/v1/fork", {})
+
+    def fork_step(self, fork_id: str, action: str) -> Dict[str, Any]:
+        """POST /v1/fork/{id}/step — advance fork by one action."""
+        return self._post(f"/v1/fork/{fork_id}/step", {"action": action})
+
+    def fork_snapshot(self, fork_id: str, actor: str = "") -> Dict[str, Any]:
+        """GET /v1/fork/{id}/snapshot — read fork cognitive snapshot."""
+        return self._get(f"/v1/fork/{fork_id}/snapshot", params={"actor": actor})
+
+    def fork_delete(self, fork_id: str) -> Dict[str, Any]:
+        """DELETE /v1/fork/{id} — discard a SimulationFork."""
+        return self._delete(f"/v1/fork/{fork_id}")
+
+    def fork_rollout(
+        self, fork_id: str, actions: List[str], sigma2_max: float = 0.25
+    ) -> Dict[str, Any]:
+        """POST /v1/fork/{id}/rollout — k-step hybrid rollout (k≤5)."""
+        return self._post(
+            f"/v1/fork/{fork_id}/rollout",
+            {"actions": actions, "sigma2_max": sigma2_max},
+        )
+
+    def consolidate(self, source_ids: List[str], summary: Dict[str, Any]) -> Dict[str, Any]:
+        """Consolidate source records into a summary via cognitive transact."""
+        delta = {"type": "Consolidate", "source_ids": source_ids, "summary": summary}
+        return self.transact(delta, actor="sdk")
+
+    def forget_actor(self, actor_id: str) -> Dict[str, Any]:
+        """GDPR hard-delete all records for actor_id via cognitive transact."""
+        return self.transact({"type": "ForgetActor", "actor": actor_id}, actor="sdk")
+
+    def archive_record(self, record_id: str) -> Dict[str, Any]:
+        """Archive or delete a record via cognitive transact."""
+        return self.transact({"type": "ArchiveRecord", "id": record_id}, actor="sdk")
+
+    def workspace_open(self, workspace_id: str, mode: str = "Private") -> Dict[str, Any]:
+        """Open a scoped workspace for isolated or shared multi-agent cognition."""
+        return self.transact({"type": "WorkspaceOpen", "id": workspace_id, "mode": mode}, actor="sdk")
+
+    def workspace_merge(self, from_id: str, into_id: str) -> Dict[str, Any]:
+        """Merge a Shared workspace into another via OR-Set CRDT convergence."""
+        return self.transact({"type": "WorkspaceMerge", "from": from_id, "into": into_id}, actor="sdk")
+
+    def retract_belief(self, belief_id: str, reason: str = "retracted") -> Dict[str, Any]:
+        """Retract a belief, triggering JTMS dependency propagation."""
+        return self.transact({"type": "RetractBelief", "id": belief_id, "reason": reason}, actor="sdk")
+
+    def trigger_consolidation(self, min_frequency: int = 3) -> Dict[str, Any]:
+        """Trigger memory consolidation to compact episodic traces into skills/beliefs."""
+        return self.transact({"type": "AutoConsolidate", "min_frequency": min_frequency}, actor="sdk")
+
+    def compute_state_diff(self, from_tx: int, to_tx: int) -> Dict[str, Any]:
+        """Return causal-attributed ΔS between two tx checkpoints."""
+        resp = self._session.post(f"{self.base_url}/v1/state/diff", json={"from_tx": from_tx, "to_tx": to_tx}, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+

{hipcortex-0.5.2 → hipcortex-1.4.0}/hipcortex/install/SKILL.md

@@ -6,6 +6,40 @@ HipCortex gives you persistent causal memory across sessions. Store decisions, r
 
 You are a memory-centric agent. The HipCortex substrate (memories + hypotheses graph as persistent beliefs + world model predictions + self health + coherence) is your primary durable mind and reasoning engine.
 
+## Lifecycle self-prompting (substrate-first at every stage)
+
+For any complex task, follow this sequence. Each step has an exit condition — never loop indefinitely.
+
+### 1. Setup (once, before loop)
+```
+recommend_tools(task)       → install recommended MCP servers + skills
+clarify_goal(task)          → structured GoalPayload + suggested success_factors + clarifying questions
+                              (if uncertainty_flags non-empty: ask user before proceeding)
+plan_validation(success_factors) → test plan: how to verify each factor
+```
+
+### 2. ReAct loop (per iteration — exits when should_exit ≠ continue)
+```
+OBSERVE:  get_live_beliefs()              → substrate state
+REFLECT:  POST /memory/reflect            → substrate CoT (before acting on ambiguous state)
+ACT:      execute tool / write / call API
+STORE:    add_memory(actor, Temporal, observation)
+          → auto-fires WMUpdater, BeliefInvalidator, EmergenceDetector
+PROGRESS: check_progress(success_factors, observations, iteration, max_iterations)
+          → if uncertainty_detected: POST /memory/reflect then POST /v1/loop/omega
+EXIT:     should_exit(iteration, max_iterations, progress_ratio, surprise_signal)
+          → continue → next iteration
+          → succeed  → store Reflexion summary, exit loop
+          → fail     → store partial results, report pending_factors to user, exit
+          → escalate → run omega loop, ask user for clarification or reduced scope, exit
+```
+
+### Exit rules (HARD — never bypass)
+- `should_exit` MUST be called every iteration
+- `max_iterations` cap is absolute — fail at the limit, never extend silently
+- Zero progress after 25% of budget → fail and reframe (call clarify_goal again)
+- High surprise (>0.8) + >50% budget + <50% progress → escalate, not continue
+
 MUST: Before any question involving project state, architecture, decisions, bugs, or context, call search_memory or get_live_beliefs (or /memory/context) first. Use substrate for state/hyp/pred.
 
 MUST: After any decision, architectural discussion, bug fix, or important finding, use /memory/ingest or add_memory (or reflect for CoT).