HydraMem

Autonomous, private Knowledge Management System with hybrid graph-vector search

Quickstart • Features • Architecture • Documentation • Contributing

What is HydraMem?

HydraMem is a 100 % local, privacy-first memory layer for AI coding agents (OpenCode, Claude Desktop, Cursor, ...). It builds a hybrid graph + vector knowledge base from your Markdown documents, runs every candidate relation through a two-stage SR-MKG topological + VoG groundedness check, and quietly refines the graph overnight via the Night Gardener — all on your machine, with zero cloud dependency by default.

Honest positioning. HydraMem is not the first memory system, the first graph-RAG, or the first hallucination filter. What it offers is an opinionated local-first integration of those patterns, with metrics you can audit (hydramem stats --raw) and a code base small enough to read in an afternoon (~5 k LOC). See docs/verification.md for what each component actually does — and does not — do.

$ hydramem stats --last-7d

╭─────────────────────────────────────────────────╮
│  HydraMem Stats – last 7 days                   │
├──────────────────────────┬──────────────────────┤
│ Tool calls               │                 142  │
│ Tokens (naive RAG)       │               1.4M   │
│ Tokens injected          │               312K   │
│ Tokens saved             │    1.09M (77.8%)     │
│ Cost saved (est.)        │             $5.45    │
│ Avg VoG score            │              0.887   │
│ Rejected by SR-MKG       │                 89   │
│ Rejected by VoG          │                 12   │
│ Cross-project hits       │                 24   │
│ Hallucinations blocked   │                  5   │
╰──────────────────────────┴──────────────────────╯

Features

Quickstart

Prerequisites

• Python ≥ 3.11 (3.12 recommended — enables the native Grafeo graph backend)
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh
• Ollama (optional, for a local LLM) — curl -fsSL https://ollama.com/install.sh | sh && ollama pull gemma4:e4b

Install

The fastest path — install the hydramem CLI into an isolated environment with uv (or pipx), then scaffold a workspace:

# install from PyPI (recommended)
uv tool install hydramem
# …or: pip install hydramem
# …or: pipx install hydramem

hydramem init ~/my-memory     # writes config.yml, kms/, data/ + an MCP snippet
cd ~/my-memory

git clone https://github.com/xusliebana/hydramem
cd hydramem
cp config.yml.example config.yml
cp .env.example .env

uv sync                                   # lightweight: ~80 MB ONNX embedder, no torch
# uv sync --extra sentence-transformers   # full stack (~2 GB, includes torch)

uv run hydramem --help                    # prefix any command with `uv run`

Ingest, search, serve

# Put Markdown files in ./kms, then ingest them
hydramem ingest ./kms

# Ask a question straight from the terminal
hydramem search "What does my documentation say about the Night Gardener?"

# Start the MCP server (stdio for MCP clients, or --transport http)
hydramem serve --transport stdio

Connect your AI client

// ~/.config/opencode/config.json
{
  "provider": {
    "ollama": {
      "model": "gemma4:e4b"
    }
  },
  "mcp": {
    "hydramem": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

// ~/.config/opencode/config.json
{
  "provider": {
    "anthropic": {
      "api_key_env": "ANTHROPIC_API_KEY",
      "model": "claude-sonnet-4-20250514"
    }
  },
  "mcp": {
    "hydramem": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

llm:
  provider: anthropic
  external:
    provider: anthropic
    api_key_env: ANTHROPIC_API_KEY
    model: claude-sonnet-4-20250514

// claude_desktop_config.json
{
  "mcpServers": {
    "hydramem": {
      "command": "hydramem",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Ingest your documents

# Put your Markdown files in ./kms, then ingest the directory
cp ~/notes/*.md kms/
hydramem ingest ./kms --project myproject

View stats

uv run hydramem stats --last-7d
uv run hydramem stats --days 30 --export md > report.md
uv run hydramem stats --days 30 --raw       # per-event baseline + injected tokens (audit mode)

How does it compare?

We will replace the qualitative checkmarks with quantitative numbers as soon as the experiment in docs/benchmarks.md ships.

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Layer 1: AI Client (OpenCode / Claude Desktop / Cursor)     │
│           Invokes Skills (.github/skills/hydramem-*)         │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTP/MCP
┌──────────────────────▼───────────────────────────────────────┐
│  Layer 2: HydraMem MCP Server (FastMCP)  hydramem/server.py     │
│           18 tools • telemetry logging • multi-provider LLM  │
└──────────┬───────────────────────┬───────────────────────────┘
           │                       │
┌──────────▼────────────┐  ┌───────▼────────────────────────────┐
│  Layer 3a:            │  │  Layer 3b:                         │
│  Verification         │  │  Night Gardener                    │
│  hydramem/verification/  │  │  hydramem/garden/gardener.py        │
│  SR-MKG + VoG         │  │  Infer → Verify → Prune           │
│                       │  │  hydramem/gnn_prune.py (LightGNN)    │
└──────────┬────────────┘  └───────┬────────────────────────────┘
           │                       │
┌──────────▼───────────────────────▼────────────────────────────┐
│  Layer 4: Storage                                             │
│  ┌──────────────────────┐  ┌────────────────────────────────┐ │
│  │ LadybugDB / Kuzu     │  │ LanceDB (vector cache)         │ │
│  │ Graph: entities,     │  │ Embeddings, ANN search         │ │
│  │ relations, chunks    │  │ (in-memory fallback)           │ │
│  └──────────────────────┘  └────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘

MCP Tools (18)

Agent Skills (6)

Configuration

HydraMem uses a layered configuration system: config.yml → environment variables → defaults.

cp config.yml.example config.yml

Multi-provider LLM

# config.yml
llm:
  provider: auto  # auto | local | ollama | openai | anthropic

  local:
    model: gemma4:e4b
    endpoint: http://localhost:11434

  external:
    provider: openai
    api_key_env: HYDRAMEM_OPENAI_KEY
    model: gpt-4o-mini

Per-subsystem LLM routing

The Night Gardener can use a different LLM than queries, saving API costs:

night_gardener:
  infer_with: local       # always infer locally (free)
  verify_with: auto       # use local if available, else external
  min_repeat_count: 2     # prefer evidence snapshots seen at least twice

verification:
  vog_use_local_llm: true # force VoG verification on local even if external is the default

Verification thresholds

verification:
  srmkg_threshold_accept: 0.7   # score ≥ 0.7 → auto-accept
  srmkg_threshold_reject: 0.3   # score < 0.3 → auto-reject
  vog_max_candidates: 30        # limit VoG calls for cost control

See docs/configuration.md for the full reference.

Night Gardener

The Night Gardener is HydraMem's autonomous offline learning engine. It runs in three phases:

1. Relation Inference — the LLM analyses locally stored query sessions and proposes new edges between entities that co-occur in successful reasoning chains. HydraMem currently stores the user query plus the grounded context returned by MCP search tools; it does not capture the client's private chain-of-thought. Repeated evidence snapshots can be prioritized with night_gardener.min_repeat_count (default 2).

   Honesty contract: if no real session text is available, the inferrer returns an empty list. It no longer invents co_mentioned placeholders (v0.1.x bug).

2. Two-level Verification:

   • SR-MKG (score ≥ 0.7 → accept, < 0.3 → reject, 0.3–0.7 → VoG)
   • VoG — LLM verifies consistency of borderline relations against source texts. Empty LLM responses or missing evidence now reject (was: random optimistic score).

3. Pruning — rule-based removal of isolated entities (now actually deleted via delete_entity) plus optional LightGNN spurious-edge detection.

# Run manually
uv run python -c "from hydramem.garden.gardener import NightGardener; print(NightGardener().run())"

# Or via MCP tool (from your AI client):
# "Run the Night Gardener on my default project"

See docs/night-gardener.md for details.

Telemetry

All metrics are stored locally in ~/.hydramem/metrics.db (SQLite). Nothing is sent anywhere unless you explicitly opt in.

hydramem stats --last-7d              # Rich table
hydramem stats --days 30 --export md  # Markdown export
hydramem stats --days 30 --export csv # CSV export
hydramem stats --days 30 --raw        # Per-event rows (audit mode)
hydramem garden-status                # Night Gardener cumulative status
hydramem garden-status --json         # Raw Night Gardener status JSON
hydramem telemetry --show             # Raw JSON
hydramem telemetry --wipe             # Delete metrics.db
hydramem telemetry --opt-in           # Anonymous aggregates (totals only)
hydramem telemetry --opt-out          # Disable sharing

hydramem stats includes both period-based telemetry and a compact cumulative Night Gardener section. Use hydramem garden-status for the Garden view on its own and --raw to audit the savings calculation event-by-event.

The "naive RAG" baseline used to compute savings is documented in hydramem/telemetry/shadow.py and is intentionally conservative — reported savings should be read as a lower bound.

See docs/telemetry.md for the schema and privacy policy.

Dogfooding

HydraMem eats its own documentation. Run:

uv run python scripts/dogfood.py

This ingests all Markdown in docs/ and kms/ into HydraMem's own graph, then runs a Night Gardener cycle. It's the quickest way to verify the full pipeline works end-to-end.

Project structure

hydramem/
├── hydramem/
│   ├── server.py               # MCP server (FastMCP, 18 tools, single-tenant)
│   ├── search.py               # Hybrid search + cached entity index
│   ├── cli.py                  # hydramem stats / telemetry / garden-status CLI
│   ├── gnn_prune.py            # Optional GNN spurious-edge pruner
│   ├── core/                   # Config, types, logging, token counting
│   ├── storage/                # GraphRepository + VectorRepository abstractions
│   │   ├── graph/              # LadybugDB / Kuzu / NetworkX backends
│   │   └── vector/             # LanceDB / in-memory backends
│   ├── llm/                    # Ollama / OpenAI / Anthropic providers
│   ├── ingest/                 # Chunker, extractor, embedder, ingest pipeline
│   ├── verification/           # SR-MKG, VoG, conflict checker, pipeline
│   ├── garden/                 # Night Gardener: inferrer, pruner, repository
│   └── telemetry/              # SQLite storage + shadow baseline + aggregator
├── kms/                        # Your knowledge files (.md)
├── docs/
│   ├── getting-started.md
│   ├── configuration.md
│   ├── architecture.md
│   ├── verification.md         # NEW – honest pipeline contract
│   ├── benchmarks.md           # NEW – reproducible experiment recipe
│   ├── roadmap.md              # NEW – living roadmap
│   ├── night-gardener.md
│   ├── telemetry.md
│   ├── mcp-tools-reference.md
│   └── opencode-setup.md
├── scripts/
│   ├── dogfood.py              # Self-ingest pipeline
│   └── benchmark.py            # NEW – benchmark scaffold
├── tests/
│   ├── unit/                   # 60+ unit tests (test_*.py at root)
│   └── integration/            # NEW – end-to-end pipeline tests
├── .github/
│   ├── workflows/              # NEW – ci.yml + release.yml
│   ├── ISSUE_TEMPLATE/         # NEW – bug + feature templates
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── skills/                 # OpenCode agent skills
├── CHANGELOG.md                # NEW – Keep a Changelog
├── CONTRIBUTING.md             # NEW
├── CODE_OF_CONDUCT.md          # NEW – Contributor Covenant 2.1
├── SECURITY.md                 # NEW – vulnerability disclosure
├── .pre-commit-config.yaml     # NEW
├── .editorconfig               # NEW
├── config.yml.example          # Full configuration reference
├── pyproject.toml
├── LICENSE                     # MIT
└── README.md

Roadmap and contributing

• Working with an AI agent? Start at AGENTS.md — the harness entry point (project map, hard rules, and nox verification commands).
• See docs/roadmap.md for what is planned and explicitly out of scope.
• See CONTRIBUTING.md for how to set up a dev environment, run the tests, and submit a PR.
• See SECURITY.md for vulnerability reporting.

License

MIT — see LICENSE. HydraMem is and will remain open-source. Anything we ship as a hosted product later will live in a separate repo.

Acknowledgements

HydraMem stands on a lot of shoulders:

• HippoRAG / HippoRAG 2 — neocortex / hippocampus offline consolidation.
• Microsoft GraphRAG — community summary verification at scale.
• FastMCP — the protocol glue that makes this useful to agents.
• LanceDB, LadybugDB, Kuzu, NetworkX, fastembed, sentence-transformers — the libraries we depend on.

If we are making a claim that conflicts with anyone's prior art, please open an issue. Honesty is a feature.

Technology stack

Running tests

uv sync --extra dev
uv run pytest -v
uv run pytest --cov=hydramem

# Tests use mocked databases and a deterministic stub embedder
# (HYDRAMEM_EMBEDDER=stub) — no Ollama, no model download, no GPU required.

_{Built with care for honest local-first memory.}