HipCortex

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 — it helps others find it. 💬 Tried it? Open an issue 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. Details: [DUALREPO.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 × probepenalty) 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 successfactors 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/atrisk/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 recordcount 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 SuccessFactors 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
• Source: 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.