v3.3.0 — Quality Metrics

HyAtlas v3.3.0 — Quality Metrics

Measure memory, not vibes. New dashboard tab with 7-day LLM token rollup on memory writes and one-click weekly baseline compare.

Highlights

• Quality Metrics sidebar page — composite, evolution, activity, and latency scores (7-day window)
• LLM token rollup on System1 extract/reconcile — GET /api/v1/metrics → llm_tokens
• GET /api/quality-metrics and POST /api/quality-baseline — snapshot at ~/.hyatlas/metrics/quality_baseline.json
• Reference benchmarks (Tencent Hy-Memory published 35% / 25% / 88%) — clearly labeled industry reference, not your instance

Upgrade

pip install -e .   # or pull latest main
hyatlas restart

Open http://127.0.0.1:8765 → Quality Metrics → Save baseline for week-over-week tracking.

Stack

Zvec · Kuzu L5–L7 · Hermes hermes-user / default · weekly digest cron

Full changelog: CHANGELOG.md

v3.1.0 — Vector Store Overhaul

Vector Store Overhaul: Qdrant → Zvec

From external vector service to embedded retrieval core. Less overhead. Faster search. Cleaner memory architecture.

What Changed

• Zvec is the sole runtime vector store — no Qdrant sidecar, no external binary, no network hop
• Qdrant runtime adapter removed — vector_store_qdrant.py and bm25_fastembed.py (Qdrant sparse BM25 encoder) deleted from runtime
• Factory is zvec-only — create_vector_store() rejects any provider other than zvec
• Config validation enforces zvec — hyatlas config validate rejects provider: qdrant
• hyatlas start never starts Qdrant — even if stale config says qdrant
• Native BM25 via Zvec FTS — no fastembed dependency, built-in full-text search on content and search_text fields
• Dashboard uses VDB API — layer counts, L1 scroll, payload enrichment via /api/v1/vdb/* endpoints (not direct Qdrant HTTP)
• hyatlas archive qdrant — cold zip backup of legacy Qdrant data
• hyatlas zvec doctor — path lock/reopen diagnostics
• Migration tooling — scripts/migrate_qdrant_to_zvec.py --apply --verify

Metrics

Metric	Value
Vector search speed	18x faster (0.9ms vs 16.4ms)
Filtered retrieval	169x faster (native filter path)
Recall quality	100% (zero precision loss)
BM25	Native (no fastembed dependency)
Operations	Qdrant removed (simpler, local backend)

Search Completeness Fixes

• _doc_to_node normalizes migrated epoch-string timestamps → ISO
• vdb_dashboard.payload_by_ids reads MemoryNode.importance/access_count (was crashing on .meta_info)

Consistency (Deep Review)

• config_cli validate enforces zvec as only runtime provider
• default_config uses zvec
• hyatlas doctor vector-store check is provider-aware
• Console TUI shows Zvec health row
• L1_RAW sweep is provider-aware (zvec path reuses live handle)
• Legacy Qdrant warning is now non-blocking with archive guidance

Upgrade Notes

1. Set vector_store.provider to zvec in your config
2. Install: pip install hyatlas-memory[zvec] (or zvec>=0.5.1)
3. Stop server, run migration: python scripts/migrate_qdrant_to_zvec.py --apply --verify
4. Run: hyatlas zvec doctor
5. Start: hyatlas start
6. Archive Qdrant: hyatlas archive qdrant

Verification

• Tests: 54 passed, 12 deselected (CI mode)
• Ruff: All checks passed (src/ + tests/)
• Security scan: No secrets, no injection risks
• Sentinel adversarial review: Passed
• Live E2E: Search ✓, layer counts ✓, graph (1444 nodes / 6374 relations) ✓, dashboard ✓, VDB scroll ✓

---

Qdrant is archived, not deleted. Safe rollback if ever needed.

v3.0.0 — Full SDK fork, L5 knowledge graph, reasoning model compatibility

v2.0.0 → v3.0.0 — Full Upgrade Overview

A full architecture evolution. From patched dependency to owned system. From text summaries to living knowledge graph.

---

What v2 established (v2.0.0 + v2.1.0)

• L5 in-process knowledge graph writer — entities extracted into Qdrant during System2 digest
• L6 schemas + L7 intentions — schemas and intentions written to Kuzu graph with cross-domain collision detection
• 1024-d embeddings — bge-large-en-v1.5 (upgraded from 384-d)
• Hybrid v2 reader — better retrieval than the legacy pipeline
• Dashboard real graph counts — L5/L6/L7 counts from live Kuzu data
• Runtime layout consolidation — HYATLAS_HOME (~/.hyatlas) root, config CLI, migration helpers
• Multi-key LLM resilience — llm.api_keys probed at startup, first valid key wins

What v3 evolves (new in v3.0.0)

Architecture

• Full SDK fork. Entire hy-memory 1.2.20 SDK (70 files, 42K+ lines) forked into src/hyatlas_memory/core/. Zero external pip dependency. Every line owned and maintained by HyAtlas.
• 23 monkey-patches → 13 first-class integrations. No more runtime patching of upstream code. Native modules. Clean, maintainable, owned.
• Unified runtime layout. Scattered paths (7+ roots) consolidated into HYATLAS_HOME (~/.hyatlas). Config CLI: hyatlas init, config show, config model, config validate.

New Features

• L5 Knowledge Graph. In-process entity/relation extraction → Kuzu graph database. Upstream hy-memory doesn't have this (their "L5" is just text summaries). Live endpoint at /api/v1/graph. Verified: 1,444 nodes, 6,374 relations.
• Emotion-Aware Memory. LLM-based valence/arousal scoring on every write. Emotionally significant memories resist time decay. Verified: valence=0.95, arousal=0.9.
• Auto-forgetting. Recency scoring + archival of stale memories.

Reliability Fixes

• Reasoning model compatibility. Think-block parsing for MiniMax-M3, DeepSeek-R1, o1-style models. Handles closed AND unclosed/truncated think blocks. agent_max_tokens raised 1024 → 8192.
• Kuzu WAL checkpoint. close() now calls CHECKPOINT + db.close() instead of just nulling references. Upstream has the same bug. Verified: 0KB WAL after shutdown (was 7MB).
• VDB circuit breaker. Protects against Qdrant failures. State: CLOSED (healthy).
• L1_RAW rolling delete + dedup. Prevents unprocessed raw points from accumulating.
• Multi-key LLM rotation. llm.api_keys list probed at startup, first valid key wins.

Model

• Switched to deepseek-v4-flash. Non-reasoning model, clean JSON output, zero parse errors. Previous: MiniMax-M3 (reasoning model requiring think-block workarounds).

CI

• Ruff lint clean. Per-file-ignores for forked upstream code, our code fixed properly. All three Python versions (3.10/3.11/3.12) pass.

Key Numbers

• 85 files changed, +29,144 lines
• 1,444 graph nodes, 6,374 relations
• 47 tests passing (33 offline + 14 server-dependent)
• 0 WAL bytes after shutdown
• 0 JSON parse errors with new model

Full changelog: https://github.com/tuancookiez-hub/HyAtlas-Memory/blob/main/CHANGELOG.md

v2.1.0 — HYATLAS_HOME runtime layout + multi-key LLM resilience

What's new in v2.1.0

• Runtime layout consolidation (HYATLAS_HOME). All runtime state now resolves under a single ~/.hyatlas root. New hyatlas config subcommands and migration helpers (hyatlas snapshot, hyatlas migrate layout).
• Multi-key LLM resilience. llm.api_keys list is probed at startup; the first working key wins. Falls back to llm.api_key for backward compatibility.
• Legacy deprecation warnings. hyatlas config show and hyatlas status warn when configs or data still live in legacy paths (~/.hy_memory, ~/.hermes/hy_memory.json).
• Config precedence: CLI flags > env vars > ~/.hyatlas/config/.env > ~/.hyatlas/config/hy_memory.json > legacy HERMES_HOME/hy_memory.json > ~/.hy_memory/pkg/.env.

See the full changelog in the repository for migration notes.

v2.0.0

HyAtlas Memory v2.0.0

What's New

• L5 in-process knowledge graph writer — entities extracted into Qdrant during System2 digest (no subprocess batch lock)
• L6 schemas + L7 intentions — schemas and intentions written to Kuzu graph with cross-domain collision detection
• Robust S2 JSON parser (Patch 18) — fixes LLM think-block wrapping that blocked all L6/L7 writes
• L4 identity dedup — pre-write cosine dedup, identity_type, evolution chains
• Hybrid v2 reader — better retrieval than the legacy pipeline
• Dashboard real graph counts — L5/L6/L7 counts from live Kuzu data
• 1024-d embeddings — bge-large-en-v1.5 (upgraded from 384-d)

Bug Fixes (post-release)

• Patch 20: S1 extractor entity_type crash — every S1 extract call was throwing KeyError because l5_kuzu_export.json uses 'type' but the extractor expected 'entity_type'. This silently killed all new L2 fact creation and froze L6/L7 growth.
• Dashboard graph-counts limit cap — /api/graph-counts endpoint still had limit=200 (the other endpoint was already fixed to 10000). Dashboard showed truncated counts for users with >200 graph nodes.
• PYTHONHOME cleanup — child processes now clear PYTHONHOME to prevent interpreter conflicts on multi-Python Windows systems.

Installation

git clone https://github.com/tuancookiez-hub/HyAtlas-Memory.git
cd HyAtlas-Memory
pip install -e .
hyatlas setup hermes

Breaking Changes

• Embedding dimension: 384 → 1024 (existing 384-d collections need migration)
• Kuzu graph dims must match new embedder
• New env defaults: HY_MEMORY_READER=hybrid_v2, MEMORY_L5_VERSION=2

Migration from v1.x

See docs/MIGRATION_v2_SCLASS.md

Known Limitations

• Kuzu WAL accumulates until clean hyatlas stop — recommend periodic restarts
• rerank_stage patch silently no-ops against current upstream reader API

Full Changelog

See CHANGELOG.md

v1.5.0 — Stable: dashboard shows all 8 layers (L0–L7)

What's fixed in v1.5.0

The dashboard now shows L5/L6/L7 from live Kuzu data, not a stale JSON export.

The problem

v1.4.2 read layer counts from l5_kuzu_export.json, last refreshed on 2026-06-18. L5/L6/L7 from Kuzu were never reflected in the dashboard, even though Kuzu had 5 L5, 449 L6, and 226 L7 nodes. The dashboard's Memory Observatory, Memory Layers table, Memory Composition bar, and Recent Ingestions feed all showed L5/L6/L7 as 0 (or missing).

The fix

• dashboard.py::_extract_memories() now iterates payload.graph.nodes from the upstream's /api/v1/list response and normalizes each into a memory dict with proper layer, content, gmt_created (Unix seconds), user_id, agent_id, etc. This makes L5/L6/L7 graph nodes flow into the dashboard's existing UI alongside L0–L4 VDB nodes.
• dashboard.py::_to_unix_ts() converts the upstream's ISO timestamp strings to Unix seconds, so the dashboard's m.gmt_created * 1000 math works without throwing Invalid time value.
• app.js::renderLayers() now prefers layerCountsData (from /api/layer-counts which now includes L5/L6/L7) over allMemories (the Qdrant sample, which is L0–L4 only) for the count column. Total is the sum of all 8 layer counts.
• /api/memories?limit=500 dedup now separates L5/L6/L7 graph items from L0–L4 VDB items, sorts by gmt_created desc, then takes the first 50 graph + 450 VDB so L5/L6/L7 are always visible in Recent Ingestions.

Verified in browser screenshots

• Memory Layers main table: L5=5, L6=216, L7=8, Total=1515 (8/8 layers populated)
• Memory Observatory Layer Stats: L5=5, L6=159, L7=84 (3D graph populates with real L5/L6/L7 nodes)
• Overview Memory Composition bar: 8/8 layer coverage, L5=6, L6=216, L7=8
• Recent Ingestions feed: L6_schema and L7_intention entries visible at top
• Field Note panel (Observatory click): shows L7 node detail with metrics (connections, linked layers, importance)

Test results

• pytest: 20/20 pass
• ruff: clean
• API: /api/layer-counts returns L5=5, L6=449, L7=226, total=1965

Upgrade

pip install --upgrade hyatlas-memory
hyatlas stop && hyatlas start --detach

Then refresh the browser — the L5/L6/L7 counts will appear immediately.

Notes

• No breaking changes. Existing installations upgrade cleanly.
• Click-to-view memory detail works on L5/L6/L7 items in the Recent Ingestions feed.

v1.4.2 — Stable: visible console + safe-to-close stack

Stable release

This is the verified-working v1.4.2 build. Code on main (commit dbcc359), the git tag (v1.4.2), and the wheel on PyPI (hyatlas-memory 1.4.2) are all in sync — no drift between source, runtime, and release artifact.

Upgrading is safe: pip install --upgrade hyatlas-memory is a drop-in replacement for any 1.x install. No breaking API changes, no config migration, no data migration.

What's in 1.4.2

🪟 hyatlas console — visible status window with live activity ticker

A read-only console window that shows:

• Live service health (Qdrant :6333, upstream :19527, dashboard :8765) — green/red ● indicator, refreshed every 2s.
• "Currently doing:" line — replaces in place with the latest interesting event.
• "Last events:" tail — last 8 memory operations (writes, recalls, S1 extraction, S2 preprocessing, reconciliation, errors).

Cross-process by design. The console tails hyatlas-memory.log so writes from any Python process (Hermes agent, dashboard, MCP) appear live.

Strictly read-only. Closing the console does NOT stop the stack.

hyatlas console

✅ hyatlas start is now safe to close

Previously, closing the visible console window sent a kill signal to the entire process tree — Qdrant + upstream + dashboard all died together. Services now always spawn with DETACHED_PROCESS. The visible console is a read-only log tailer; the stack runs independent of any window.

> hyatlas start                  # safe to Ctrl+C / close the terminal once "ready"
> hyatlas console                # open the status window whenever you want
> hyatlas stop                   # actually shut the stack down

🩹 Dashboard L5 graph 503 — root-cause path mismatch

Writer (l5_export_json.py) and reader (4 sites in dashboard.py) used different hardcoded paths for the L5 export JSON. Neither used Hermes' canonical home resolver. Single _l5_export_path() helper now shared by writer (2 sites) and reader (4 sites). Dashboard graph endpoint returns 200 with actual data.

🔇 Lint-clean CI

All 20 ruff violations from the v1.4.2 console code are fixed. ruff check src/ tests/ passes. 20/20 tests pass.

Install / upgrade

pip install --upgrade hyatlas-memory
hyatlas setup hermes

That sets the plugin shim and auto-starts Qdrant + upstream + dashboard on the next Hermes session. Two-command deployment.

Quick reference

hyatlas start           # start the stack
hyatlas stop            # stop the stack
hyatlas status          # what's running
hyatlas console         # live status window
hyatlas doctor          # full health check
hyatlas setup hermes    # install plugin + config

Full changelog

See CHANGELOG.md for the complete 1.4.2 entry and prior versions.

Verification

End-to-end live-tested:

• Console window renders, health indicator updates every 2s
• sync_turn from a separate venv Python — console ticker captured upstream pipeline's S1 extraction, S1 reconciliation, S2 preprocessing, cross-domain sweeper warning in real time
• Closed the console window with stack running — services stayed up (regression test for the parent-process-group bug)
• hyatlas console --help lists the subcommand
• L5 graph endpoint returns 200 on the dashboard

Compatibility

• Python 3.10+
• Qdrant 1.x
• Windows / macOS / Linux
• Same ~/.hermes/hy_memory.json config format as 1.2.x / 1.4.0 / 1.4.1 — no migration needed

v1.0.1 — Patch

HyAtlas-Memory v1.0.1 — Patch

Fixes hyatlas CLI to work from any directory after pip install hyatlas-memory.

Fixed

• hyatlas start|--stop|--status from any directory — previously failed with "start.py not found" when run outside the repo root after pip install. Startup logic is now bundled in hyatlas_memory._start and resolves the project root via HYATLAS_PROJECT_ROOT env var → cwd → editable-install detection.
• CLI now accepts both status and --status (and stop, help).

Docs

• README: new "Retrieval scoring (4-factor MemoryScorer)" section, L0 layer added to the table, dashboard page names corrected, install-from-PyPI path, PyPI + GitHub release badges.

Install

pip install --upgrade hyatlas-memory

Or set the env var to run hyatlas from anywhere:

export HYATLAS_PROJECT_ROOT=/path/to/hyatlas-memory

See CHANGELOG.md for full notes.

v1.0.0 — First Stable Release

HyAtlas-Memory v1.0.0 — First Stable Release

The community implementation of the official Hy-Memory 7-layer cognitive memory framework (Tencent Hunyuan) for Hermes Agent. Includes the experimental L7 intention layer. MIT licensed.

Install

pip install hyatlas-memory

What's new

• First stable release on PyPI
• Layer-as-importance scoring (default ON) — maps memory layers to upstream MemoryScorer weights: l4_identity=1.0, l2_fact=0.8, l3_summary=0.6, l0_basic_info=0.5, l1_raw=0.3
• Access-count tracking (default ON) — bumps access_count on every recall, completing upstream's 4-factor scorer
• Qdrant auto-detection — no more hardcoded paths; uses QDRANT_BIN env var → PATH → common OS locations; skips launch if Docker already running
• Token-based dashboard auth when bound to 0.0.0.0 (auto-generated 32-char token, cookie session, /api/health exempt)
• Docker one-command startup via docker-compose up -d
• Dashboard front-end refactor — app.js split into core + js/l5.js + js/observatory.js
• Integration tests in tests/test_integration.py covering the full local stack

Kill switches

Both scoring features are ON by default. To disable:

export HYATLAS_MEMORY_IMPORTANCE=0
export HYATLAS_MEMORY_ACCESS_COUNT=0

See CHANGELOG.md for the full notes.