| name | hyatlas-memory |
| description | Long-term memory stack for Hermes Agent — install, use, and troubleshoot HyAtlas-Memory (7-layer cognitive memory with System1/System2 dual processing, profile isolation, local in-process embedder). |
| version | 3.4.5 |
| author | Tuna Dev <tuancookiez@gmail.com> |
| license | Apache-2.0 |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["memory","hyatlas","hermes-agent","long-term-memory","kuzu","zvec","sentence-transformers","bge","local-embed","knowledge-graph","profile-isolation"],"homepage":"https://github.com/tuancookiez-hub/HyAtlas-Memory","related_skills":["hermes-agent"]}} |
HyAtlas-Memory
HyAtlas-Memory is a personal, local, single-user long-term memory stack for Hermes Agent. It is forked from the Hy-Memory 7-layer cognitive memory framework (Tencent Hunyuan, memory.hunyuan.tencent.com) and tuned for one user's daily, multi-session use. Includes the experimental L7 intention layer. Apache 2.0 licensed.
What it gives Hermes:
- Auto-recall — relevant memories are injected into the agent's context at the start of every turn (no tool call needed).
- Capture — every conversation is broken into atomic facts across 7 memory layers (L1 raw → L7 intention).
- Background evolution — System2 digests merge duplicates, resolve contradictions, refine the model of you over time.
- Local, private — your memories live on your disk under
~/.hyatlas/. No API keys required for embedding (sentence-transformers runs in-process). LLM key is BYO (OpenRouter / OpenAI / anything OpenAI-compatible).
- Profile isolation — multiple agents (default, research, trading, etc.) each get their own memory namespace via
agent_id. The dashboard lets you filter to one profile at a time.
- Dashboard — live view at
http://127.0.0.1:8765 with layer counts, recent activity, knowledge graph, settings.
When to use this skill:
- User asks about HyAtlas, hy-memory, hermes memory, or "my memory stack".
- User reports a memory issue:
embed: error on /api/v1/status, search returns nothing, layer counts off, dashboard not loading.
- User wants to install / upgrade / uninstall HyAtlas.
- User wants to write a memory from the CLI or read from a specific layer.
- You're about to make a change that touches how memory flows (add a tool that calls
hermes memory write, etc.) and need to know the conventions.
Install
Single command. No PyPI involvement as of v3.4.5 — install is GitHub-direct.
pip install git+https://github.com/tuancookiez-hub/HyAtlas-Memory.git
hyatlas setup hermes -y
hyatlas start
Verify:
hyatlas doctor
hyatlas status
Upgrade (preserves your ~/.hyatlas/ data):
pip install --upgrade --force-reinstall git+https://github.com/tuancookiez-hub/HyAtlas-Memory.git
hyatlas stop && hyatlas start
CLI quick reference
| Command | What it does |
|---|
hyatlas start | Start server + dashboard (detached by default) |
hyatlas stop | Stop both |
hyatlas status | One-line health: ports, status, embed, llm |
hyatlas doctor | Fail-fast health check; exit 1 on issues |
hyatlas add "..." | Write a memory fact |
hyatlas search "..." | Search memories, returns L4 identity layer hits |
hyatlas list --layer L5 | List memories from a specific layer |
hyatlas setup hermes -y | Wire the plugin into Hermes (memory.provider=hy_memory) |
hyatlas --help | Full command list |
Full help: hyatlas <command> --help (every subcommand is documented).
HTTP API
Server listens on 127.0.0.1:19527. Useful endpoints (all GET unless noted):
| Endpoint | Purpose |
|---|
/api/v1/status | Health: status, vdb, embed, llm, embed_dims, write_pipeline |
/api/v1/search?q=<text>&agent_id=<id> | Semantic search, returns L4 hits |
/api/v1/list?agent_id=<id>&limit=N | List recent memories, with optional include_raw=true to see the original L1_RAW payload |
/api/v1/vdb/layer_count?agent_id=<id> | Per-layer VDB counts (l1..l7) |
/api/v1/profiles | List known agent profiles and their counts |
/api/v1/layer-health?agent_id=<id> | Both VDB and graph layer counts in one call |
/api/v1/add (POST) | Write a memory: {"text": "...", "agent_id": "default", "user_id": "hermes-user"} |
All endpoints accept ?agent_id=<id> to scope to a profile. Default is default.
Dashboard: http://127.0.0.1:8765 — visualizes everything above. Profile dropdown in the top-right.
Identity contract
When Hermes is the client, writes go to:
| Field | Value |
|---|
user_id | hermes-user (override via HY_MEMORY_USER_ID env var) |
agent_id | default — Hermes TUI / gateway writes here |
mode | ultra (full L1→L7 pipeline) |
Do NOT use default_agent for Hermes writes. That namespace is reserved for legacy L5 blobs from before the agent_identity unification.
To check what's in each profile: GET /api/v1/profiles returns counts per agent_id.
Layer model
Memories are stored across 7 layers. Knowing what each is for helps debugging:
| Layer | Name | What lives here | When populated |
|---|
| L1 | l1_raw | Original raw text from the user/conversation | Every turn, before any LLM |
| L2 | l2_fact | LLM-extracted atomic facts from L1 | System2 digest (background) |
| L3 | l3_context | Session context, conversation windows | During sessions |
| L4 | l4_identity | Stable user/agent identity facts (preferences, traits) | Replayed from L1 → L2 reconciliation |
| L5 | l5_knowledge | Knowledge graph nodes — entities + relations | Cross-domain sweeper, weekly |
| L6 | l6_schema | Schema evolution records | L5 in-process extraction |
| L7 | l7_intention | High-level intentions / goals | Experimental, weekly digest |
Common gotcha: search returns L4 hits by default. If a memory exists at L1 but isn't surfacing in search, it means System2 hasn't promoted it to L4 yet — wait for the weekly digest, or run a search with ?include_raw=true to see unprocessed L1 entries.
Local embedder (no API key)
The embedder runs in-process via sentence-transformers. No API key needed, no provider, no external call. Model: BAAI/bge-large-en-v1.5 (1024 dims, 3.1s load on CPU). Matches the existing agent_memories_1024 zvec collection.
If embed: error shows on /api/v1/status, the in-process wire failed. Diagnostic:
"C:/Users/tuanc/AppData/Local/hermes/hermes-agent/venv/Scripts/python.exe" -c "
from hyatlas_memory.integrations import wire_inprocess_embed
from hyatlas_memory.core.core.embed_service import EmbedService
wire_inprocess_embed(EmbedService)
print('wired:', getattr(EmbedService, '_inprocess_embed_wired', False))
"
Version matrix that works (as of v3.4.5):
transformers==4.46.3huggingface-hub<1.0,>=0.23.2 (not 1.x — that's the bug v3.4.2 fixed, v3.4.5 enforces)tokenizers<0.21,>=0.20sentence-transformers==3.0.1numpy<3torch
LLM config
LLM is BYO key. Default config in D:/HyAtlas/.hyatlas/config/hy_memory.json:
"llm": {
"api_key": "sk-or-...",
"model": "tencent/hy3:free",
"base_url": "https://openrouter.ai/api/v1",
"extra_body": {"reasoning_effort": "none", "include_reasoning": false}
}
The extra_body suppresses reasoning tokens that would otherwise consume the LLM's output budget before JSON. If you swap to a different provider, keep extra_body or shorten the System2 prompts.
Files and paths
| Path | What |
|---|
D:/HyAtlas/.hyatlas/config/hy_memory.json | Active config (LLM key, embedder model, vector store) |
D:/HyAtlas/.hyatlas/data/kuzu_db/ | Kuzu graph (L1 raw, L2 fact, relations) |
D:/HyAtlas/.hyatlas/data/zvec/ | zvec in-process vector store |
D:/HyAtlas/.hyatlas/logs/hy_memory.log | Server log (rotates daily) |
D:/HyAtlas/.hyatlas/logs/dashboard.log | Dashboard log |
Override HYATLAS_HOME to relocate everything (e.g., to another drive).
Weekly digest
A script-only cron job runs every 7 days:
- Source:
scripts/run_hyatlas_digest_launcher.py in repo
- Installed at:
%LOCALAPPDATA%\hermes\scripts\run_hyatlas_digest.py
- Schedule: every 168h / 10080m
- Delivery:
discord:1523091423556276365 (same thread as smart-memory-prune)
Manual trigger (Windows):
python %LOCALAPPDATA%\hermes\scripts\run_hyatlas_digest.py
Do NOT run the digest from git-bash in background — MSYS path mangling breaks it. Use the launcher.
Common errors and fixes
embed: error on /api/v1/status
- sentence-transformers import chain failed.
- Check version matrix above. v3.4.5+ should have correct pins.
- Restart:
hyatlas stop && hyatlas start.
vdb: error
- zvec store unreadable (corruption or lock file).
hyatlas doctor will tell you. hyatlas stop && rm D:/HyAtlas/.hyatlas/data/zvec/LOCK && hyatlas start as last resort (data-preserving).
llm: error
- OpenRouter key invalid or rate-limited.
- Check
~/.hyatlas/config/hy_memory.json llm.api_key.
Search returns nothing after a write
- New write went to L1_RAW but System2 hasn't promoted to L4 yet.
- Either wait for the weekly digest, or pass
?include_raw=true to see L1 entries.
- Force-promote by writing directly with
layer: L4 (rare; usually let the digest do it).
Dashboard tabs show empty
- Check profile dropdown — you may be on a profile with no data.
- Switch to
default to see Hermes's main namespace.
Port :19527 already in use
hyatlas stop, wait 5s, hyatlas start. If still stuck, check Windows netstat -ano | findstr :19527 and kill the orphan PID.
Versioning and releases
Releases are GitHub-only. No PyPI. Install is pip install git+https://... (no version pin → gets latest). To pin a specific version: pip install git+https://github.com/tuancookiez-hub/HyAtlas-Memory.git@v3.4.5.
Release flow:
- Bump version in
pyproject.toml, _version.py, both plugin.yaml files
- Update CHANGELOG.md
git tag -a v3.X.Y -m "..."git push origin v3.X.Y- Maintainer runs
gh release create v3.X.Y --notes-file <changelog-snippet>
Latest release: see https://github.com/tuancookiez-hub/HyAtlas-Memory/releases
Repository conventions
- Default branch:
main. PRs target main.
- Apache 2.0 license (NOT MIT — note: there's a stale MIT-licensed
hyatlas-memory package on PyPI from before the fork, different artifact, ignore it).
- Python 3.10–3.12 (CI tests all three).
- Tests:
pytest -v -m "not integration" for unit; pytest -m integration for live-stack tests (requires server running).
- Lint:
ruff check src/ tests/. Format: ruff format --check src/ tests/ (currently disabled in CI; 116 files need reformatting).
When to escalate vs. handle yourself
Handle yourself:
- Status check, install, upgrade
- Layer counts explanation
- CLI command lookup
- Profile isolation explanation
- Reading the config file
Stop and ask the user:
- The user wants to delete or migrate
~/.hyatlas/ data
- The user wants to add a new provider / change LLM model
- Something fails that's not covered above
- A schema or version migration is needed
Never do:
- Don't
rm -rf ~/.hyatlas without explicit confirmation
- Don't upload to PyPI (the project does not publish there)
- Don't switch embedder to a different model without user confirmation (changes 1024-dim vector compatibility)
How to install this skill
If you found this file on GitHub and want your Hermes to load it:
/skills install https://raw.githubusercontent.com/tuancookiez-hub/HyAtlas-Memory/main/docs/SKILL.md --name hyatlas-memory
mkdir -p ~/.hermes/skills/hyatlas-memory
curl -fsSL https://raw.githubusercontent.com/tuancookiez-hub/HyAtlas-Memory/main/docs/SKILL.md \
-o ~/.hermes/skills/hyatlas-memory/SKILL.md
After install, this skill loads whenever Hermes sees a question about HyAtlas, hy-memory, memory issues, dashboard, or this stack in general. Hermes reads the description: field from YAML frontmatter to decide when to load it.
