🐉 HydraMind

Persistent memory for coding agents that knows when it may be wrong.

A graph-native MCP server that stores facts in HydraDB, tracks contradictions and revisions, propagates lost trust through provenance, and abstains instead of hallucinating.

Quickstart · Tools · How it works · Dashboard · Contributing · Roadmap

Table of contents

• Why HydraMind?

• Features

• Quickstart

• Connect a coding agent

• MCP tools

• How it works

• Dashboard

• Demo and evaluation

• Configuration

• Data model

• Testing and quality

• Project layout

• Limits and guarantees

• Roadmap

• Contributing

• Security

• Acknowledgements and license

Related MCP server: MegaMemory

💡 Why HydraMind?

Agents forget between sessions. Worse, the memory tools that fix that tend to treat every stored sentence as equally true forever. When a fact changes, the old claim and everything concluded from it keep ranking just as high.

HydraMind treats uncertainty, revisions, and provenance as graph data:

Recall combines a scoped graph match with a transparent text score. If there is no evidence it returns [], so the agent can abstain instead of inventing an answer.

Built for Hack Hydra, Track 03: Memory + Context Retrieval and the Best Use of HydraDB prize. Judges can start with the Track 03 judge guide.

✨ Features

• Eight MCP tools with typed schemas: remember, recall, revise, timeline, trace_memory, check_conflict, explain_trust, forget.

• Sessionless MCP 2026-07-28 over stdio, plus explicitly stateless Streamable HTTP.

• Trust that moves. Contradictions lower the older claim by 0.40, then lower its dependents for two hops by 0.15 × hop, with a 0.05 floor.

• Explicit time. revise closes valid_to, writes a dated, reasoned SUPERSEDED_BY edge, and keeps the old fact auditable.

• Evidence traces through HydraDB's native algo.SSpaths engine, with scope guards.

• First-class abstention. Insufficient keyword evidence returns [], including tested domain-overlap hard negatives.

• Retry-safe writes. Idempotency keys repair interrupted writes without applying decay twice.

• No embeddings, no hosted model calls, and no per-token bill on the retrieval path.

• Live React dashboard on the same memory service. Every trust change you see is persisted in HydraDB.

• Docker is not required anywhere.

• Tested: unit, live Bolt, real MCP stdio, stateless HTTP, restart, and concurrency tests, plus a repeatable stress gate.

🚀 Quickstart

Prerequisites

• Linux or macOS. Windows is not supported yet because local write coordination uses POSIX fcntl locks (#29).

• Python 3.11+ and uv (or plain pip).

• A source-built HydraDB graph-node listening on neo4j://127.0.0.1:7687. See HydraDB's local server instructions.

• The auth token that graph-node reads from GRAPH_AUTH_TOKEN_FILE.

HydraMind was checked against HydraDB commit 6a2fbb1 (August 13, 2026).

1. Install

git clone https://github.com/himanshu748/hydramind.git
cd hydramind
uv sync --extra dev --locked

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

2. Point it at HydraDB

export HYDRAMIND_TOKEN='local-development-token-32-bytes'

.venv/bin/python -c 'from hydramind.db import HydraDB; db = HydraDB(); db.verify_connection(); db.setup_schema(); print("HydraDB Bolt connection OK"); db.close()'

All settings are listed in Configuration and .env.example.

3. Run

HydraMind uses the official MCP Python SDK v2 and negotiates the sessionless 2026-07-28 protocol, so requests never depend on a handshake or server-side session. Every durable fact, relationship, and trust event lives in HydraDB. See the SDK's MCP 2.0 changes.

🔌 Connect a coding agent

Codex CLI

codex mcp add hydramind \
  --env HYDRAMIND_TOKEN=local-development-token-32-bytes \
  --env HYDRAMIND_URI=neo4j://127.0.0.1:7687 \
  -- /absolute/path/to/hydramind/.venv/bin/hydramind

Claude Desktop, Cursor, and other JSON-configured hosts

{
  "mcpServers": {
    "hydramind": {
      "command": "/absolute/path/to/hydramind/.venv/bin/hydramind",
      "env": {
        "HYDRAMIND_URI": "neo4j://127.0.0.1:7687",
        "HYDRAMIND_USERNAME": "neo4j",
        "HYDRAMIND_TOKEN": "local-development-token-32-bytes",
        "HYDRAMIND_DATABASE": "default"
      }
    }
  }
}

Restart the host after editing. Outside local development, inject the token through the host's secret management instead of committing it to a config file.

HTTP clients: use http://127.0.0.1:8788/mcp. HydraMind forces JSON responses and stateless_http=True, so a fresh client can recall data written by another client. Bind to a non-loopback address only behind an authenticated gateway.

🧰 MCP tools

Example session

remember("Production deploys must always use direct routing.", "acme", ["deploy-policy"])
remember("Checklist follows deploy policy.", "acme", ["checklist"], derived_from=[root_id])
remember("Production deploys must not use direct routing.", "acme", ["deploy-policy"])
recall("How should production route?", "acme", ["deploy-policy"])
revise(runtime_id, "Agents use Python 3.13.", "acme", reason="Toolchain upgraded")
timeline("acme", "agent-runtime")
trace_memory(root_id, "acme")

The newest claim stays at trust 1.0, the older claim becomes contradicted at 0.6, and the dependent checklist loses 0.15. Both claims remain auditable.

🧠 How it works

flowchart LR
    New["new memory<br/>trust 1.00"] -->|"CONTRADICTS<br/>time + reason + trust delta"| Old["older memory<br/>trust 0.60"]
    Child["derived memory<br/>trust 0.85"] -->|DERIVED_FROM| Old
    Grandchild["two-hop derivative<br/>trust 0.70"] -->|DERIVED_FROM| Child
    Prior["Tuesday fact<br/>superseded"] -->|"SUPERSEDED_BY<br/>valid_to + reason"| Current["Wednesday fact<br/>active"]
    New -->|ABOUT| Entity["Entity"]
    Old -->|ABOUT| Entity
    Prior -->|ABOUT| Entity
    Current -->|ABOUT| Entity

1. Write. remember links the memory to scoped entities and optional parents.

2. Detect. A small, replaceable polarity heuristic (conflict.py) checks active same-entity memories before the write.

3. Propagate. On contradiction, the older claim drops by 0.40, and incoming DERIVED_FROM dependents drop by 0.15 × hop for two hops. Each drop is stored as an immutable TRUST_DECAY event.

4. Recall. Candidates in scope are scored by trust_score × keyword_overlap. Anything below 0.80 coverage is dropped, so an empty list means "no evidence".

5. Explain. explain_trust and trace_memory turn the graph back into plain language and evidence paths.

flowchart TB
    Agent["Coding agent<br/>(Codex, Claude, Cursor, ...)"] -->|MCP stdio / stateless HTTP| Server["hydramind.server"]
    Browser["Browser"] -->|JSON API| Web["hydramind.web<br/>+ React dashboard"]
    Server --> Service["MemoryService<br/>hydramind.tools"]
    Web --> Service
    Service --> Conflict["conflict.py<br/>polarity heuristic"]
    Service -->|official neo4j driver, Bolt| HydraDB[("HydraDB<br/>graph-node")]

📊 Dashboard

The React interface ships prebuilt inside the repository and Python package, so it works right after install:

.venv/bin/hydramind-ui

• http://127.0.0.1:8787/: landing page with an interactive trust cascade.

• http://127.0.0.1:8787/app: live HydraDB dashboard to seed a demo graph, recall, remember, revise, inspect timelines, run native traces, explain trust, and forget.

The UI uses the same Python memory service as the MCP tools. To work on the UI itself, see UI development.

🎬 Demo and evaluation

With HydraDB running and HYDRAMIND_TOKEN set:

.venv/bin/python examples/demo.py          # add --keep to retain the isolated graph
.venv/bin/python -m benchmarks.track03_eval

The demo creates an isolated graph, shows two-hop provenance, catches a revision before write, shows trust propagation and ranking, explains the old claim, proves abstention, and cleans up.

The six-case Track 03 evaluation covers cross-service continuity, explicit chronology, missing-information abstention, contradiction decay, two-hop provenance decay, and native evidence tracing. A raw passing run is checked in at benchmarks/results/track03-evaluation.json. It is a small reproducible smoke evaluation, not a LongMemEval result or a claim of superiority over vector stores.

1. Show the Memory/Entity graph and the two-hop DERIVED_FROM chain.

2. Insert an opposing production policy and show the persisted CONTRADICTS edge.

3. Show trust changing 1.0 → 0.6, 1.0 → 0.85, and 1.0 → 0.70.

4. Revise the runtime fact and show the dated SUPERSEDED_BY timeline.

5. Trace a memory through native algo.SSpaths, then ask for absent information and get [].

🔧 Configuration

HydraMind reads these from the process environment. To load .env.example after copying it to .env, run set -a; . ./.env; set +a. Startup fails clearly when HydraDB or its token is unavailable.

🗂 Data model

(:Memory {
  id, content, source, created_at, valid_from, valid_to,
  scope, trust_score, status, write_phase
})
(:Entity {id, name, kind, scope})

(:Memory)-[:ABOUT]->(:Entity)
(:Memory)-[:CONTRADICTS {detected_at, reason, before_trust, after_trust, apply_status}]->(:Memory)
(:Memory)-[:SUPERSEDED_BY {revised_at, reason}]->(:Memory)
(:Memory)-[:DERIVED_FROM {
  last_decayed_at, last_decay_reason, before_trust, after_trust, decay_hop, caused_by
}]->(:Memory)
(:Memory)-[:TRUST_DECAY {
  detected_at, reason, before_trust, after_trust, hop, caused_by, apply_status
}]->(:Memory)

• External memory IDs are strings, because JSON and JavaScript cannot safely represent every 63-bit integer. HydraDB stores them as non-negative integer vertex IDs.

• Entity IDs are stable 63-bit hashes of scope plus name, so identical names cannot bridge scopes.

• Each TRUST_DECAY edge is an immutable event. The summary fields on DERIVED_FROM support quick inspection without overwriting history.

• HydraDB uses schema-on-write and does not support CREATE CONSTRAINT, so startup creates a versioned HydraMindSchema marker. Writes use session.run(...) auto-commit statements because the current Bolt runtime has no explicit transactions. Queries stay within HydraDB's documented Cypher compatibility surface.

🧪 Testing and quality

.venv/bin/pytest -m 'not integration'                                  # no database needed
HYDRAMIND_TOKEN=local-development-token-32-bytes .venv/bin/pytest      # full live suite
.venv/bin/ruff check src tests examples
.venv/bin/ruff format --check src tests examples
.venv/bin/mypy src

The live suite covers graph writes, scoped recall, entity filtering, ranking, abstention, contradiction and two-hop decay, trust explanations, revision chronology, scope-safe native tracing, non-destructive forgetting, real MCP stdio and stateless HTTP round trips, persistence across processes, concurrent and cross-process write races, idempotent retries with failures injected at five auto-commit boundaries, the dashboard HTTP handler, and the Track 03 evaluation.

Baseline (August 15, 2026): 48 tests (18 database-independent, 30 live), 91% coverage of the MCP and HydraDB core. CI rebuilds the UI and checks it matches ui/dist, then runs Ruff, mypy, the database-independent tests, and uv build.

Stress gate

HYDRAMIND_TOKEN=local-development-token-32-bytes \
  .venv/bin/python benchmarks/product_stress.py \
  --writes 250 --workers 8 --recall-probes 50 \
  --output benchmarks/results/product-stress-250.json

On the pinned local HydraDB node this wrote 250/250 unique memories at 4.747 writes/s (2,910 ms write p95), verified 50/50 exact recall targets at 40.1 ms p50 and 41.4 ms p95, and recalled the target after a fresh-driver restart. The raw result is at benchmarks/results/product-stress-250.json. It measures durability and backpressure on one machine, not maximum throughput.

📁 Project layout

src/hydramind/
  db.py          HydraDB connection, Bolt errors, schema marker
  conflict.py    Replaceable conflict heuristic
  tools.py       Memory graph and the eight tool implementations
  server.py      MCP server v2 tools, sessionless stdio, stateless HTTP
  web.py         Local JSON API and landing/dashboard server
ui/src/          React + Vite + TypeScript dashboard (built output in ui/dist)
examples/        Terminal demo
benchmarks/      Track 03 evaluation, stress gate, checked-in results
tests/           Unit, live HydraDB, MCP transport, and web tests
design.md        Design system for visual surfaces

🧭 Limits and guarantees

These limits are deliberate and documented so you can tell what is guaranteed from what is future work.

• Lexical, not semantic. Conflict detection and relevance use transparent keyword heuristics. conflict.py isolates the classifier so it can be replaced.

• Bounded graph work. Trust propagation stops at two hops. Traces stop at three hops and 100 paths. Recall returns at most 100 ranked results.

• Recall scans the scope. Every eligible candidate in a scope is scored. Large deployments should partition scopes and benchmark latency.

• Not crash-atomic. HydraDB's Bolt surface is auto-commit only. Local writers are coordinated, and keyed remember retries repair unfinished phases. Unkeyed writes and revisions are not distributed transactions.

• Scope is not auth. Scope partitions and guards queries. It is not authentication or tenant authorization. Put an authenticated gateway in front of any remote, multi-user deployment.

🗺 Roadmap

Ideas where contributions are especially welcome:

• Pluggable semantic conflict classifier behind the conflict.py interface (#9)

• Optional embedding-assisted recall that keeps the abstention guarantee (#11)

• Indexed candidate selection for very large scopes (#14, #15)

• Configurable decay constants and hop limits (#7, #8)

• Packaged releases on PyPI (#17)

• Larger public benchmark runs, such as LongMemEval (#27)

• Windows support (#29)

• More MCP host setup guides (#18, #19)

Browse all open issues. Have another idea? Open a feature request.

🤝 Contributing

Contributions of all sizes are welcome, from typo fixes to new retrieval strategies. Start with CONTRIBUTING.md for setup, workflow, and coding standards, and look for issues labelled good first issue.

Everyone taking part is expected to follow the Code of Conduct. Notable changes are recorded in the changelog.

🔒 Security

Please do not open public issues for vulnerabilities. See SECURITY.md for private reporting.

🙏 Acknowledgements and license

HydraMind started as original Hack Hydra hackathon work. It builds on:

• HydraDB: external AGPL-3.0 software accessed over Bolt, not vendored.

• MCP Python SDK (MIT) and the Neo4j Python driver (Apache-2.0).

• React, Vite, TypeScript, and Lucide for the UI. Bundled Inter, IBM Plex Mono, and Space Grotesk fonts use the SIL Open Font License.

Dependency versions and license metadata are in uv.lock and ui/package-lock.json.

HydraMind is released under the MIT License.

If HydraMind helps your agents remember responsibly, please ⭐ the repo.