Metadata-Version: 2.4
Name: hipcortex
Version: 3.18.2
Summary: Cognitive reconstruction engine for AI agents — Python SDK + CLI. Loop-Ready Contract: cursor-paged settle feed (snapshot_transitions: next_cursor, horizon_tx, truncated) + structural causal model view (snapshot_scm); KARM contract surface: CognitiveSnapshot with laws/policies/failures/uncertainty, CognitiveStateProvider/Sink traits; LawExtractor; PolicyRegistry; MDL sparsity GC; 64-tool / 7-resource MCP; WAL-persistent. LangChain, AutoGen, CrewAI, MCP
Author: HipCortex Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/farmountain/HipCortex
Project-URL: Repository, https://github.com/farmountain/HipCortex
Project-URL: Issues, https://github.com/farmountain/HipCortex/issues
Project-URL: Benchmark, https://github.com/farmountain/HipCortex/blob/main/BENCHMARK.md
Keywords: ai,memory,langchain,autogen,crewai,llm,agents,rag
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: httpx>=0.27
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
Provides-Extra: crewai
Requires-Dist: crewai>=0.28; extra == "crewai"
Requires-Dist: crewai-tools>=0.1; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == "autogen"
Provides-Extra: benchmark
Requires-Dist: mem0ai>=0.1; extra == "benchmark"
Requires-Dist: tabulate>=0.9; extra == "benchmark"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: all
Requires-Dist: langchain-core>=0.1; extra == "all"
Requires-Dist: llama-index-core>=0.10; extra == "all"
Requires-Dist: crewai>=0.28; extra == "all"
Requires-Dist: crewai-tools>=0.1; extra == "all"
Requires-Dist: pyautogen>=0.2; extra == "all"
Requires-Dist: mem0ai>=0.1; extra == "all"
Requires-Dist: tabulate>=0.9; extra == "all"
Dynamic: requires-python

# HipCortex Python SDK (`v3.18.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 (64 tools)
hipcortex channels # honesty matrix (native / mcp / framework / guide)
```

**Version matrix:** pip / Cargo / MCP `serverInfo` / VS Code VSIX = **3.18.2**; the TypeScript SDK source is **3.12.0** (npm registry `0.5.2`). See [docs/channels.md](../../docs/channels.md).

---

## What's new in 3.18 — Loop-Ready Contract

An external control loop can now take one snapshot and then follow the changes:

```python
snap = client.cognitive_snapshot(actor="agent")         # bootstrap once
cursor = snap["tx_cursor"]

page = client.snapshot_transitions("agent", since=cursor)
if page["truncated"]:
    snap = client.cognitive_snapshot(actor="agent")     # fell behind the horizon: re-bootstrap
else:
    for t in page["transitions"]:
        ...                                             # upsert by t["intent_id"]
    cursor = page["next_cursor"]

scm = client.snapshot_scm()   # ScmView: nodes, equations, edges, interventions, acyclic, as_of_tx
```

Settled intents are stamped by the server, `ok` is true only for a received receipt that reported success, and the feed keeps the newest 4096 settles; `horizon_tx` is the newest evicted stamp, and a cursor below it gets `truncated: true`. MCP exposes the same pair as `snapshot_transitions` and `snapshot_scm` (64 tools, 7 resources).

---

## ⚡ 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")
```
