# HipCortex

> Deterministic cognitive state substrate & world model runtime for autonomous agents. Features transactional belief updates, hybrid RK4 rollouts, and 3-tier experience consolidation via MCP & REST.

- **Type:** MCP server
- **Install:** `agentstack add mcp-farmountain-hipcortex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [farmountain](https://agentstack.voostack.com/s/farmountain)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [farmountain](https://github.com/farmountain)
- **Source:** https://github.com/farmountain/HipCortex
- **Website:** https://github.com/farmountain/HipCortex/blob/main/BENCHMARK.md

## Install

```sh
agentstack add mcp-farmountain-hipcortex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HipCortex

[](https://pypi.org/project/hipcortex/)
[](https://www.npmjs.com/package/hipcortex)
[](LICENSE)
[](https://github.com/farmountain/HipCortex/releases/latest)

**Autonomous agents have no persistent cognitive state — goals lost between calls, beliefs stale, actions never feeding back into reasoning. HipCortex is the cognitive state substrate that closes the loop: goal scheduling, belief revision, world model feedback, and decision provenance — served locally over MCP + REST.**

⭐ **If that solves a pain you feel, [star the repo](https://github.com/farmountain/HipCortex)** — it helps others find it.  
💬 **Tried it?** [Open an issue](https://github.com/farmountain/HipCortex/issues) or leave a 👍/👎 comment — real feedback steers the next release.

This repository is the **public developer surface** (docs, client SDKs, connectors, issues, release artifacts). New engine development lives in private [`hipcortex-core`](https://github.com/farmountain/hipcortex-core). Details: [DUAL_REPO.md](DUAL_REPO.md) · [NOTICE](NOTICE).

---

## Why it exists

Every agent invocation starts cognitively blind. Goals set in one call vanish before the next. Beliefs accumulated from observations are never revised when contradicted. Actions taken by the agent never update its world model. Decisions leave no audit trail. There is no loop — just isolated acts.

HipCortex is the substrate that closes it: a **local causal graph** of goals, beliefs, decisions, and observations, with a reasoning loop that feeds every action back into prediction, served over **HTTP + MCP** to any agent host.

| Without HipCortex | With HipCortex |
|-------------------|---------------|
| Goals re-stated every call | GoalScheduler tracks + prioritizes across sessions |
| Stale beliefs silently persist | BeliefInvalidator detects contradictions, decays confidence |
| Actions never update world model | WorldModelUpdater closes the feedback loop |
| Decisions leave no trace | DecisionPayload + provenance chain per act-phase |
| Agent doesn't know what it's allowed to do | ActionRegistry + ExecutionGate answer that in one call |
| Probe target selection is blind | IG-ranked probes (epistemic × deficit × probe_penalty) select highest-information entity first; grounded → never re-probed |
| Probe outcomes don't update the world model | `update_from_receipt` writes dual transitions (meta-probe + domain `P(s′\|s,a)`) into WM |
| Successful probes leave beliefs unchanged | `BeliefExecutive::reinforce` via `derived_from`/`evidence` provenance — not substring |
| IDE exit breaks autonomy | Headless `IntentRunner` polls and dispatches intents without the IDE open |
| Action ordering within a goal is arbitrary | `GoalScheduler::plan_action_sequence` orders success_factors by WM MAP probability — grounded first |
| Tool recommendation ignores actuator liveness | `filter_liveness` removes probe-failed/stale MCP servers using WM `entity_contact` heartbeats |
| 3-month claim backed only by unit suites | `soak_sit.rs`: 500-iter temporal decay + WM convergence + bounded-growth proof |
| No public differentiation metric vs Mem0/Zep/Letta | 10-question substrate scorecard with code refs + `GET /substrate/scorecard` |
| Unknown sensor probe returns fake `ok=True` | Honest grounding: unknown sensor → `{reachable:False, error:"unknown_sensor:"}` — WM never poisoned (v3.1.0) |
| Restate renames factor but never flags next step | `blocked_factors` + `probe_required` Temporal per blocked factor, `derived_from=goal_id` (v3.1.0) |
| Context cost grows with transcript — no OpEx proof | `get_budget` MCP tool: `substrate_tokens` vs `naive_transcript_tokens`; consolidation ratio durable via `GET /substrate/budget` (v3.2.0) |
| Wall guard meter claims host context coverage | Honest `wall_status` (bounded/at_risk/exceeded) + `[honest]` disclaimer: only MCP output metered; per-actor `_live_beliefs_seen_actors` discipline (v3.3.0) |
| 3-month claim backed only by WAL reopens | Published field log: real server subprocess + HTTP + file edit + kill+restart → `after_restart=14` PASS; 605 stale VSIX assets deleted (v3.4.0) |
| Soak proves record_count survives, not epistemic update | `/intent/open` → `hashlib.sha256` → `/intent/receipt` → `was_surprising=True` → `Belief{confidence=0.3}` → `uncertain_count↑` after silent edit; WAL-preserved across kill+restart (v3.5.0) |
| Soak script was the hasher — not truly unattended | `scripts/hipcortex_runner.py` autonomously hashes file + posts all intent/receipt; soak script only edits file + reads scorecard; Q10 advances past `probe_entity:X` after all intents Received; `ClarifyEngine` self-prompting gate (MAX 3 rounds, deduped, guaranteed exit) (v3.6.0) |
| One-shot runner ≠ long-lived goal; two-runner confusion; success_factors never marked satisfied | `--guided` daemon reads scorecard `recommended_op`, probes entities or calls `POST /goal/:id/react`; `score_success_factors_from_intents` marks factors satisfied from Received intents → `goal.status = Succeeded` across multiple iterations (v3.7.0) |
| Completion heuristic thin; runner still dual-role; no continuous service proof; no drift detection | `was_surprising=true` required in scorer; `_poll_and_receipt` single-role runner; production-pair systemd/NSSM service configs + deployment doc; `consecutive_low_score >= 3 → GoalRevision Reflexion` (v3.8.0) |
| Fallback open kept dual path; count-based "done"; GoalRevision flag only; no measured multi-day log | `allow_open=False` in guided mode (hard single-role); `observation_pattern` predicate per `SuccessFactor`; `ClarifyEngine::apply_revision` synthesises new factors from active entities; `generate_field_log.py` produces 24h session artifact (v3.9.0) |
| Passive capture required per-channel client instrumentation — VSIX break silently killed memory | Universal server-side Axum middleware captures every mutation (POST/PUT/DELETE) from any channel — MCP, VSIX, REST, CLI, LangChain — zero client changes; `X-Actor` header attribution; `AppState.passive_capture_enabled`; fire-and-forget Temporal write; 262 integration tests 0 failures (v3.10.0) |
| Clarify ladder was advisory; a removal could not be persisted through the store's own primitives; `/memory/embed` and `/memory/query` drifted from the write path's vocabulary; CI never executed several suites that existed | Clarify H1–H10 closed and the ladder made authoritative; durable removals + `delete_by_ids`/`upsert`/`delete_by_actor` store primitives; one guardrail and one `record_type` vocabulary across `/memory/add`, `/memory/embed`, `/memory/query`; pipeline enforcement G1–G8 — CI now runs the suites it previously skipped (v3.11.0) |

---

## What's new in v3.11.0 — Authoritative Clarify Ladder, Durable Removals, Pipeline Enforcement

Closes the gaps identified after v3.10.0: the clarify protocol existed but was advisory; a deletion could not be persisted through the store's own primitives; and CI never executed several suites that existed — which is how a `record_type` mismatch reached `main` behind a green pipeline.

| Change | Gap | Fix |
|--------|-----|-----|
| **Clarify ladder made authoritative** | H1–H10 gaps left `ClarifyEngine` advisory — a provably blocked goal could sit open | `feat(clarify)`: the ladder is now the authority for blocked goals, with bounded rounds, deduped prompts and a guaranteed exit; `ladder_rungs` / `ladder_exit_reasons` are reported on the goal routes |
| **Durable removals** | `MemoryBackend` exposes only load/append/flush/clear, so a deletion had no way to persist | `MemoryStore::delete_by_id`, `delete_by_ids`, `delete_by_actor` — removal is persisted, and consolidation routes through the bulk primitives instead of rewriting the store |
| **One `record_type` vocabulary** | `/memory/query` and `/memory/embed` accepted values the write path rejected | Both run the write path's guardrail and share its `record_type` vocabulary |
| **Identifiers are not content** | The safety guardrail classified record ids as personally-identifiable content | The guardrail classifies record *content*, never identifiers |
| **Self-describing integrity** | A record could not say which hash format produced its integrity | `MemoryRecord.hash_version`, stamped `INTEGRITY_FORMAT_VERSION` and compared on load |
| **gRPC record literal completed** | The gRPC path built a partial `MemoryRecord` literal that no CI job compiled | Literal completed |
| **One intervention shape** | World-model rollout accepted two intervention shapes depending on what the model knew | One shape, whatever the world model knows |
| **Pipeline enforcement (G1–G8)** | CI never ran `v040_contract_sit`, the acceptance suite, `--test property_suite` under `web-server`, or the jest suite; nothing validated the staged VSIX server binary | All four now run in CI; the VSIX packaging step validates the staged server's *version*, not its file size |
| **MCP surface proven by execution** | The declared tool surface was asserted from prose rather than from calling it | MCP self-test repaired and run in CI; `forget_actor` reduced to one contract; every dispatched handler's globals asserted; bundled mirror resynced |
| **Gates that assert the declaration, not a copy (G17–G18)** | A test that hard-codes the value it verifies is a restatement, not a gate; and a gitignored artifact read as present | Version assertions bind to the declaration; the VSIX binary check builds synthetic fixtures instead of reading a gitignored path |
| **Seven SITs lost to cargo lock contention (G19)** | `integration_suite --features web-server` read 313 passed / 0 failed locally but 306 passed / 7 failed in CI | The seven SITs now spawn the cargo-built executable instead of shelling out to `cargo run`, removing the shared target-directory lock; 60 s budget as margin |

Test coverage: 366 lib + 517 unit + 182 minimal / 313 web-server integration + 59 property + standalone `v040_contract_sit`, 0 failures.

---

## What's new in v3.10.0 — Universal Server-Side Passive Capture

Closes the gap identified after v3.9.0: passive memory capture required per-channel client instrumentation — a VSIX break silently killed memory for that channel.

| Change | Gap | Fix |
|--------|-----|-----|
| **Universal passive capture** | Each channel needed its own client-side capture hook; a broken VSIX silently lost memory | Server-side Axum middleware captures every successful mutation (POST/PUT/DELETE) as a `Temporal` record — MCP, VSIX, REST, CLI, LangChain, AutoGen, CrewAI: one middleware, all channels, zero client changes |
| **`X-Actor` header attribution** | Captured records had no actor source | Each record carries the actor from the `X-Actor` header (defaults to `unknown-channel`); MCP server sends `X-Actor: mcp` on every request |
| **`AppState.passive_capture_enabled`** | Per-request env reads raced under concurrency | Flag resolved once at startup from `HIPCORTEX_PASSIVE_CAPTURE` (default `true`) |
| **Fire-and-forget write** | Capture added latency to the HTTP path | `tokio::spawn` — zero latency added to the response path |
| **4 structural ACs** | No passive-capture test coverage | `tests/integration/passive_capture_sit.rs`: capture fires on POST, no capture on GET, disabled flag suppresses all, unknown-channel actor default |

Test coverage: 366 lib + 473 unit + 262 integration + 56 property + 4 AC-PC (v3.10.0) + 10 AC-390 (v3.9.0) + earlier suites, 0 failures.

---

## What's new in v3.9.0 — Hard Single-Role, Predicate Scorer, GoalRevision→ClarifyEngine, Field Log

Closes four gaps identified after v3.8.0: fallback open kept runner as cognition source under race; "done" was still count-gated not predicate-gated; GoalRevision wrote a flag but never applied new ACs; no measured multi-day runtime artifact.

| Change | Gap | Fix |
|--------|-----|-----|
| **Hard single-role guided mode** | `_poll_and_receipt` fallback could open intents in guided mode | `allow_open=False` in `run_guided` probe path — runner never opens intents; logs `waiting (single-role mode)` when no daemon intents found |
| **Observation-content predicate scorer** | Factor satisfied by count of surprising receipts, not actual content match | `SuccessFactor.observation_pattern: Option`; scorer checks `content_excerpt` (first 256 bytes of watched file sent in receipt) against pattern; `accept_receipt_impl` persists `content_excerpt` to intent MemoryRecord |
| **GoalRevision → ClarifyEngine apply_revision** | `Reflexion{goal_revision_proposed}` written but never acted on | `ClarifyEngine::apply_revision` scans recent Intent entities, adds new `SuccessFactor`s for uncovered entities, writes `Reflexion{goal_restated_from_revision}`; on failure writes deduped `Belief{clarify_needed, source=goal_revision_drift}` → NeedsUserClarification; called from ReactEngine immediately after GoalRevision emit |
| **24h field log artifact** | No measured multi-day runtime log | `scripts/generate_field_log.py` produces `docs/field_logs/production_pair_24h.json`: 3 sessions × 8h, 2 restarts, WAL survival rate 1.0, goal Succeeded at end |

Field log: `docs/field_logs/production_pair_24h.json` — `total_hours=24`, `total_restarts=2`, `goal_survived_all_restarts=true`, `final_goal_status=Succeeded`.

Test coverage: 366 lib + 10 AC-390 (v3.9.0) + 10 AC-GS (v3.8.0) + earlier suites, 0 failures.

---

## What's new in v3.8.0 — Production-Grade Goal Lifecycle: Semantic Completion + Drift Detection

Closes four gaps identified after v3.7.0: completion heuristic was count-based not semantic; no continuous service / multi-day soak proof; runner still opened intents (dual-role); no drift detection for long-horizon goals.

| Change | Gap | Fix |
|--------|-----|-----|
| **Semantic completion scorer** | `hits >= 2 Received intents` ≠ AC text is true | `score_success_factors_from_intents` now filters `was_surprising==true`; `accept_receipt_impl` persists `was_surprising` to intent MemoryRecord metadata |
| **Production-pair service** | No IDE-closed continuous service documented | `scripts/production_pair_setup.py` generates systemd/NSSM configs for server + runner; `docs/production_deployment.md` documents restart proof; diary `continuous_service=true` |
| **Single-role runner** | `run_guided` could open intents (daemon role leaked into runner) | `_poll_and_receipt()` polls `GET /intent/open` for daemon-opened intents; opens only as fallback; `run_guided` probe path calls `_poll_and_receipt` not `_open_intent` |
| **Long-horizon drift detection** | Env change after goal creation has no detection path | `GoalPayload.consecutive_low_score`; `critic_score ` mode: polls scorecard `recommended_op` → probes on `probe_entity:X` → calls `POST /goal/:id/react` on `react_loop` → exits when `status=Succeeded` |
| **Factor scorer in ReactEngine** | `loop_engine.rs` checked `all_satisfied` but nothing ever set `factor.satisfied = true` | `score_success_factors_from_intents` called each iteration: counts Received intents per entity; `hits >= 2` marks factor satisfied; persisted to MemoryStore before `all_satisfied` check |
| **Long-run soak scenario** | `scripts/unattended_soak_scenario.py` drove one change then exited | New `scripts/longrun_soak_scenario.py`: creates goal first, starts guided runner, makes 3 file edits, waits for `Succeeded`, writes diary with `goal_status`, `success_factors_satisfied`, `react_iterations`, `goal_lifecycle` |

Field diary: `docs/longrun_soak_example.json` — `goal_status=Succeeded`, `success_factors_satisfied=true`, `react_iterations>=2`, `goal_lifecycle=[Pending, InProgress, Succeeded]`.

Test coverage: 366 lib + 10 AC-LR (v3.7.0) + 10 AC-UA (v3.6.0) + earlier suites, 0 failures.

---

## What's new in v3.6.0 — Unattended Runner: Runner Hashes, Script Only Edits

Closes the "soak script was the hasher" gap identified after v3.5.0: `scripts/hipcortex_runner.py` is the autonomous sensor. The soak script contains no `hashlib`, no `/intent/open`, no `/intent/receipt`. Runner exits cleanly leaving

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [farmountain](https://github.com/farmountain)
- **Source:** [farmountain/HipCortex](https://github.com/farmountain/HipCortex)
- **License:** Apache-2.0
- **Homepage:** https://github.com/farmountain/HipCortex/blob/main/BENCHMARK.md

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-farmountain-hipcortex
- Seller: https://agentstack.voostack.com/s/farmountain
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.