{"id":"0c5ad2a1-0a6e-44eb-a6ba-e84612b7a90f","slug":"hypermind-engine","kind":"mcp","name":"HyperMind-engine","summary":"","owner":"Sidiora-Labs","repoUrl":"https://github.com/Sidiora-Labs/HyperMind-engine","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-09-16T05:00:45.000Z","addedAt":"2026-10-21T18:05:08.931Z","logoUrl":"https://avatars.githubusercontent.com/u/315858149?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T16:30:09.312Z","sample":false,"url":"https://conduits.dev/tools/hypermind-engine","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![HyperMind](https://supabase.paxeer.app/storage/v1/object/public/json/readme_hp.png)\n\n# HyperMind\n\nDurable, evidence-aware memory for AI agents. Remember across sessions, recover after restarts, and build bounded context without confusing recalled text with authority.\n\n[English](README.md) · [简体中文](README.zh-CN.md) · [हिन्दी](README.hi.md) · [Español](README.es.md) · [Français](README.fr.md) · [العربية](README.ar.md) · [Português](README.pt.md) · [Русский](README.ru.md) · [日本語](README.ja.md) · [Deutsch](README.de.md)\n\nActive development: **v1.0.0 is not qualified or released**. Source is available; benchmark targets, local test results, and release qualification are different claims. See [current evidence and limitations](docs/evaluation/results.md).\n\n## Why HyperMind?\n\nAgent context windows are temporary; useful memory must survive process exits without losing where information came from. HyperMind is a Rust memory engine with local storage, explicit provenance, and interfaces for both embedded applications and long-running agents.\n\n- Durable events: an encrypted append-only ledger, replayable projections, checkpoints, and restart continuity.\n- Evidence-bearing recall: lexical retrieval, optional embeddings, time-aware beliefs, disputes, and source references.\n- Bounded activation: assemble relevant context within a token budget and retain untrusted-memory labels.\n- Observed follow-up: intentions, predictions, outcomes, quiet-hours attention batches, and supported procedures.\n- Multiple surfaces: stdio MCP, a Unix-socket daemon, authenticated gRPC/REST, and source SDKs.\n\n## How it fits together\n\n```text\nMCP / CLI / SDK / gRPC / REST\n              |\n       actor + capability\n              |\n     append-only event ledger\n              |\n     projections + indexes\n              |\n  recall -> activation -> safe rendering\n```\n\nThe ledger is the source of truth; projections and indexes are derived views. Remembering a claim does not verify it. Activation produces evidence-labeled context, not executable instructions. [Architecture](docs/concepts/architecture.md) · [Authority model](docs/concepts/authority.md)\n\n## Build and install from source\n\nUse a Unix development host with Git, rustup, and a native C/C++ toolchain (compiler/linker, make, CMake, Perl, and pkg-config). The repository pins Rust 1.93.0. Rust dependencies and the protobuf compiler are resolved by the build; dependency downloads require network access.\n\n```sh\ngit clone https://github.com/Sidiora-Labs/HyperMind-engine.git\ncd HyperMind-engine\nrustup toolchain install 1.93.0 --profile minimal\ncargo build --locked -p hm-cli -p hm-mcp\ncargo install --path crates/hm-cli --locked\ncargo install --path crates/hm-mcp --locked\n```\n\nThese commands install this checkout, not published registry packages. Put Cargo’s binary directory on your client’s PATH. The default lexical path needs no model download or provider key. See the [installation guide](docs/start/quickstart.md).\n\n## Connect an MCP client\n\nAfter installation, initialize private state and register the stdio server. This two-command example uses Claude Code:\n\n```sh\nhm init --path .hypermind --json\nclaude mcp add hypermind -- hm-mcp --config .hypermind/hypermind.conf\n```\n\nFor other clients, use an equivalent MCP server entry. Replace the configuration path with an absolute path and ensure the client can find `hm-mcp`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hypermind\": {\n      \"command\": \"hm-mcp\",\n      \"args\": [\"--config\", \"/absolute/path/.hypermind/hypermind.conf\"]\n    }\n  }\n}\n```\n\nTry `remember` with `{\"conversation\":\"demo\",\"kind\":\"user\",\"content\":\"The region is eu-central-1.\"}`, then `recall` with `{\"mode\":\"lexical\",\"query\":\"region\",\"limit\":5}`. The [14-tool catalog](docs/reference/generated/tools.md) covers remember, recall, activate, believe, retract, dispute, intend, bind, predict, outcome, attest, consolidate, inspect, and forget.\n\nRun **one owner per actor directory**: MCP, daemon, or an embedded engine—not concurrent writers. The generated configuration contains keys and actor/admin capabilities; keep it private and out of version control.\n\n## Use the daemon and CLI\n\nStop the MCP owner first. Start the daemon in one terminal:\n\n```sh\nhm serve --config .hypermind/hypermind.conf --json\n```\n\nIn another terminal, append a memory, retrieve ledger IDs, and request a context bundle:\n\n```sh\nhm remember --config .hypermind/hypermind.conf --conversation demo \\\n  --content \"The deployment region is eu-central-1.\" --json\nhm recall --config .hypermind/hypermind.conf --query \"deployment region\" --json\nhm activate --config .hypermind/hypermind.conf --conversation demo \\\n  --query \"deployment region\" --budget-tokens 1024 --json\n```\n\nDaemon `recall` currently returns `lsns`, not a rendered answer; daemon `activate` returns a base64-encoded HMA1 bundle. Use the MCP interface or an SDK renderer for memory text. CLI `--embedded` is an alternative only after the daemon has stopped. [CLI contracts](docs/reference/cli.md)\n\n## Remote access requires mutual TLS\n\nRemote listeners are opt-in. Provide a server certificate/key, a trusted client CA, and a valid capability token in the client. Run this instead of the local-only daemon; the paths below refer to certificates you provision:\n\n```sh\nhm serve --config .hypermind/hypermind.conf \\\n  --grpc-bind 127.0.0.1:7443 --rest-bind 127.0.0.1:8443 \\\n  --tls-cert /secure/server.pem --tls-key /secure/server.key \\\n  --tls-client-ca /secure/client-ca.pem --json\n```\n\nKeep actor and admin listeners separate; a client certificate alone does not grant actor authority. See [remote deployment](docs/guides/deployment.md), [protocol contracts](docs/reference/protocol.md), and [Docker, Compose, systemd, and Helm setup](deploy/README.md). No prepublished image is implied.\n\n## SDK entry points\n\nSDKs live in this repository. Package publication and cross-language release qualification are separate work; source availability is not a promise of npm, PyPI, or prebuilt binary availability.\n\n| Language | Source | Entry points |\n| --- | --- | --- |\n| Rust | [hm-serve](crates/hm-serve/src/embedded.rs) | `HyperMind::open`, `session`, `remember`, `recall`, `activate`, `render` |\n| TypeScript | [sdk/typescript](sdk/typescript) | `@hypermind/client`: `Client.connect`; `engine`, `render`, `migrate` |\n| Python | [sdk/python](sdk/python) | `Engine.open`, `session`, `remember`, `recall`, `activate`, `render`; `Client` (mTLS) |\n| Go | [sdk/go](sdk/go) | `centra/core/cortexclient`: `Dial`, `Session`, `Remember`, `Recall`, `Activate` |\n\nChoose an embedded owner or a daemon client, not both for the same actor. Python requires 3.10+; Go declares 1.25.0. TypeScript build scripts live in its workspace. See [SDK guidance](docs/reference/sdks.md) and the [source-derived API catalog](docs/reference/generated/sdk-api.md) for current signatures.\n\n## Optional providers through Centra\n\nLocal lexical memory works without a remote provider. Enable only the features you need in the environment of the owning process; this example explicitly enables all three provider-backed paths:\n\n```sh\nexport CENTRA_GATEWAY_URL=\"https://gateway.centra.ag/v1\"\nexport CENTRA_GATEWAY_API_KEY=\"<your-secret-key>\"\nexport HM_EMBEDDING_PROVIDER=centra\nexport HM_RECONSTRUCTION_PROVIDER=centra\nexport HM_CONSOLIDATION_PROVIDER=centra\n```\n\nEmbedding uses `openrouter/openai/text-embedding-3-large`. Reconstruction and consolidation use **`openrouter/openai/gpt-5.6-luna` through `CENTRA_GATEWAY_URL`**. These opt-ins do not change the independent benchmark configuration. Historical recorded fixtures are not new provider calls.\n\nNever commit real keys or put them in MCP JSON. Provider use sends selected content outside the process and can incur charges; obtain data-transfer authorization and set an explicit spend budget first. Model artifact downloads are opt-in and do not, by themselves, enable local ONNX inference. [Configuration](docs/reference/config.md)\n\n## Evidence, authority, and limits\n\n- Recalled memory is untrusted data, never a system/developer instruction or permission to act.\n- Claims, attestations, observed tool outcomes, and derived procedures retain distinct evidence roles.\n- Quiet hours and attention policy control follow-up; a prediction is not proof that its outcome happened.\n- Ledger encryption does not imply every projection, export, log, or SDK buffer is encrypted. Protect the whole state directory.\n- Single-writer ownership matters. This is not a distributed multi-writer database or a credential vault.\n- Inspect `ok`, `health`, `gaps`, and provenance; transport success alone does not mean complete or correct memory.\n\nRead the [threat model](docs/security/threat-model.md) before exposing a service or importing untrusted history.\n\n## Benchmarks: targets are not results\n\nThe specification sets these acceptance targets:\n\n| Gate | Target—not a measured claim |\n| --- | --- |\n| LongMemEval | 500 questions; accuracy ≥ 0.90 |\n| LoCoMo | Full coverage; non-adversarial F1 ≥ 0.75 |\n| Recall@10 | ≥ 0.95 at 10k items |\n| Warm activation | p99 < 10 ms at 100k items |\n\nThe complete local LongMemEval run scored **459/500 (91.8%)**, using Luna through Centra with lexical-only retrieval. LoCoMo is running; its qualification remains pending. The focused real slice-7 journey also passed. These results do not establish hosted CI or release qualification. See [measured status and evidence](docs/evaluation/results.md) and [evaluation methodology](docs/evaluation/methodology.md).\n\n## Develop and check documentation\n\nFrom the repository root, use the focused journey and documentation checks below. Documentation tooling additionally needs Node.js and mdBook:\n\n```sh\ncargo test -p hm-sim --test slice7_journey\nnode docs/tools/catalog.mjs --write\ncargo run -p hm-eval -- docs-gate\nmdbook build docs\n```\n\nThe catalog command regenerates documented public surfaces from actual source. `docs-gate` rejects stale coverage and broken local links; it does not certify prose accuracy or external URLs. Follow [AGENTS.md](AGENTS.md) and the [task specification](spec/hypermind-01/spec.kvx) for scoped work and qualification.\n\n## Repository map\n\n| Path | Contents |\n| --- | --- |\n| `crates/` | Rust kernel, storage, cognition, surfaces, CLI, and evaluation tools |\n| `schemas/` | Canonical FlatBuffers and protobuf contracts |\n| `sdk/` | TypeScript, Python, and Go source packages |\n| `docs/` | mdBook, generated reference catalogs, and ADR-001–010 |\n| `eval/` | Dataset tooling, benchmark definitions, and evidence reports |\n| `deploy/` | Source-build container and deployment manifests |\n| `spec/` | Requirements, design, workflow, and task state |\n\nStart with the [documentation index](docs/SUMMARY.md).\n\n[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Support](SUPPORT.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Contributors](CONTRIBUTORS.md)\n\n## License\n\nApache-2.0, as declared by the Rust workspace. See [LICENSE](LICENSE) and [NOTICE](NOTICE) for separately identified material. Review upstream model and dataset licenses separately; the project license does not relicense those assets.\n"}