tuancookiez-hub/HyAtlas-Memory

cgo is required — onnxruntime-go links against the platform's C runtime via cgo. You need a C compiler (gcc, clang, or MinGW-W64).

git clone https://github.com/tuancookiez-hub/HyAtlas-Memory.git
cd HyAtlas-Memory
go build -o hyatlas-go ./cmd/hyatlas-go                     # plain build (small; reads the model from a models/ folder at runtime)
go build -tags embedded -o hyatlas-go ./cmd/hyatlas-go       # embedded build (about 160 MB, model and onnxruntime bundled in)

For the embedded build to compile, cmd/hyatlas-go/models/ must contain four files, because go:embed lists them by name: bge-small-en-v1.5.onnx, bge-small-en-v1.5.onnx.data (an empty file is fine), vocab.txt, and the onnxruntime library for your platform: libonnxruntime.so on Linux, libonnxruntime.dylib on macOS, onnxruntime.dll on Windows. See Model assets for where to get them.

# Local BGE embeddings (the "no Python" path) are the default. Set HYATLAS_MODEL_DIR
# only for a plain build whose model is not in one of the search-order folders in
# "Model assets" below. An embedded build ignores it.
export HYATLAS_EMBED_BASE=bge
export HYATLAS_MODEL_DIR=/path/to/models

# Required for LLM extraction in pro/ultra. No endpoint is assumed: without all
# three the server stores the raw trace only and reports llm=unconfigured.
# Any OpenAI-compatible API works, including a local one.
export HYATLAS_LLM_BASE="https://inference-api.nousresearch.com/v1"   # example
export HYATLAS_LLM_MODEL="poolside/laguna-s-2.1:free"                 # example
export HYATLAS_LLM_KEY="your-nous-agent-key"

./hyatlas-go

The server listens on 127.0.0.1:19528 (loopback only by default). It has no authentication, so keep it on loopback. Use HYATLAS_GO_HOST to change the bind address only if you understand the exposure.

Who may talk to it. The server refuses requests that a web page could make on your behalf, on every bind address:

• A Host header that names a DNS name is refused with 403, including on /healthz. Only localhost and IP literals pass. This blocks DNS rebinding. To accept a hostname, such as a LAN name or a reverse proxy, list it in HYATLAS_ALLOWED_HOSTS. Entries are hostnames (no scheme, and any port in an entry is ignored). Then the server accepts that name.
• An Origin header that is not loopback, not the request's own host, and not in the allowlist is refused with 403. A null or non-http(s) origin is refused too.
• A request with Sec-Fetch-Site: cross-site is refused with 403.
• Requests with no Origin header (curl, the Hermes plugin) are not affected by the Origin rule, and the server's own /dashboard/ pages are not affected.

Each write returns an extraction_status: pending (extraction runs in the background), done or failed (the write waited for extraction), unconfigured (no LLM endpoint, model or key), or skipped (lite mode).

Privacy — what leaves your machine

The server binds loopback only, but loopback is not the whole story, and the default configuration is not fully local:

So out of the box: embeddings and storage are local, and extraction stays off until you configure an endpoint. Once HYATLAS_LLM_BASE, HYATLAS_LLM_MODEL and HYATLAS_LLM_KEY are all set, every write in pro or ultra is sent to that endpoint to derive facts, summaries and intentions. That is the point of the feature, and it means choosing the endpoint is choosing where the text goes. The endpoint is yours to choose: any OpenAI-compatible API, including one on your own machine. To keep conversation text on the machine, set HYATLAS_MODE=lite: no LLM call is made at all, so only the raw trace and local embeddings are stored. (lite keeps text local only while HYATLAS_EMBED_BASE is bge or local; an HTTP embedder receives the text too.)

The three modes form a ladder of reasoning scope, not of latency:

The two systems own disjoint layers:

• System1 (per turn) — L1 Profile, L2 Raw, L3 Fact, L7 Intention, L8 Entity pages. What one turn can actually evidence. L4 Summary comes from episodes: the writes of one owner with no gap longer than HYATLAS_EPISODE_GAP (30 minutes) form one stretch of work, which gets one summary when it ends. That costs one LLM call per episode, not per write.
• System2 (slow path) — L5 Knowledge, L6 Schema. A relation worth keeping is corroborated by more than one turn, and a schema is a recurring pattern, so neither can come from a single turn. Ultra is the only mode that runs System2, which is why it is the only one that fills L5 and L6. HYATLAS_CONSOLIDATE_GRAPH=off stops L5 (and the arc).

Whether a write blocks on its extraction is a separate knob (HYATLAS_SYNC_EXTRACT=on|off), not part of the mode. Pro blocks by default and ultra does not, but either can be overridden — capability follows the mode, latency follows the knob.

Ultra-only tuning:

Durations are Go durations (30m, 6h, 2160h) or a plain number of seconds. Go has no d unit, so write 90 days as 2160h. A value that does not parse is logged and treated as unset, so raw decay stays off.

HYATLAS_CONSOLIDATE_BATCH caps the facts one owner sends per call. An owner with more facts than the cap is split into several clusters, each its own call.

HYATLAS_RAW_RETENTION is opt-in because it deletes. An L2 raw row is kept if a live graph edge cites it (as its primary source or any of its sources), or if a live fact (L1 or L3) was extracted from it. Only raw rows that are old and cited by nothing are removed. The decay pass runs once per consolidation pass, so raw rows can age out only when a pass runs.

Facts that the ultra pass merges or drops are superseded, not deleted: they keep invalid_at and superseded_by, and GET /api/v1/list returns them only with include_superseded=true.

The 8 / 8 above is steady state, not the first minute. A fresh ultra install sits at 6/8 until the slow path first runs, which is up to 6h away by default. L5 is filled only when a pass finds relations corroborated by at least two turns, and L6 only when a pass finds recurring patterns. To run a pass now, instead of waiting for the tick:

curl -X POST http://127.0.0.1:19528/api/v1/digest

The response wraps the pass in report: digest_ok: true, then report with facts_in, owners_run, owners_unchanged, skipped_owners, clusters_run, clusters_pending, merged, edges, dropped, schemas, arc, pruned_raw, protected_raw, duration_ms and errors. edges counts distinct L5 edges created. Re-citing an existing edge adds evidence and is not counted.

/api/v1/status carries consolidations (the number of completed passes) and last_consolidated (the last report), so "the slow path ran" is checkable rather than something you have to take on faith. Both reset when the server restarts, so they count passes since the current process started. consolidations is -1 when the mode has no slow path (lite and pro). A pass that finds nothing to reconcile still reports as run with zero changes, which is what distinguishes it from a pass that never happened. An owner whose facts have not changed since its last successful pass counts under owners_unchanged and is not sent to the LLM again.

At the end of a pass, an owner with at least 4 live schemas from at least 2 topics also gets a cross-topic pass, at most once per HYATLAS_CROSS_SCHEMA_EVERY (24h; the last run is kept in consolidate_state.json, so a restart does not repeat it). One extra LLM call, at most once a day per owner, sends that owner's schema texts (newest 40) and asks for up to 3 patterns that hold across two or more of them. Each is written as a new L6 schema marked cross_topic, with the facts behind the schemas it generalises as evidence, unless the owner already has a schema that says the same (the 0.92 duplicate guard). Existing schemas are never retired or edited by it. The report counts them under cross_schemas.

Facts are consolidated in topic clusters of up to HYATLAS_CONSOLIDATE_BATCH facts, built once per owner and kept in consolidate_state.json. An owner here is a person: user IDs grouped by HYATLAS_USER_ALIASES are consolidated together, so a contradiction between facts written under two of their IDs meets in one call. A new fact joins the cluster of its nearest neighbour (similarity 0.55 and up) when that cluster has room, otherwise the newest time-ordered cluster. A cluster is due only when its members changed since its last successful call, so after the first full coverage a pass handles just the clusters that received new facts. A pass runs due clusters across owners, up to HYATLAS_CONSOLIDATE_PARALLEL (2) calls at once, and starts no call when less time is left in its 10-minute budget than a call takes: 1.25 times the median of recent successful calls, at least 3 minutes. While clusters are still due (clusters_pending > 0) the next pass runs after HYATLAS_CONSOLIDATE_CATCHUP (20m) instead of HYATLAS_CONSOLIDATE_EVERY, and a server started with work pending begins with a catch-up pass. How long the first coverage takes depends on the model: on a free model with 25-fact clusters a pass ran 7 clusters in 9 minutes, about half a day for ~150 clusters. Progress is saved after every cluster. A cluster that fails three passes in a row is skipped until its members change or 24 hours pass, and the skip is listed in errors; when two or more calls of a pass fail and none succeeds, the provider is taken to be down and no cluster is charged. A failed LLM call, merge or supersede makes the cluster retry on the next pass. A failed arc, schema, L5 edge or L1 mirror write is listed in errors but does not cause a retry, because the facts were already reconciled.

Otherwise the endpoint is yours to choose per the tier you are on — set HYATLAS_LLM_BASE, HYATLAS_LLM_MODEL and HYATLAS_LLM_KEY to any OpenAI-compatible API, or point HYATLAS_LLM_BASE at a server you host (ollama, vLLM, llama.cpp, LM Studio) and leave HYATLAS_EMBED_BASE=bge.

Nothing is transmitted until all three are set. There is no default endpoint, so a fresh install makes no LLM call at all: writes store the raw trace plus local embeddings, status reports llm: "unconfigured", and each write reports extraction_status: "unconfigured". Once you configure an endpoint, extraction runs on every write in pro and ultra and your turn text goes there — so choosing the endpoint is choosing where memory text leaves the machine. Set HYATLAS_MODE=lite to opt out entirely regardless of configuration.

When the Hermes plugin spawns this server it passes an explicitly allowlisted environment — OS essentials plus HYATLAS_* only — rather than a copy of the agent's environment, so provider API keys the agent holds do not reach the server process. The plugin forwards only the non-secret LLM endpoint and model settings, and only when you have set them in the plugin config. It forwards no LLM key at spawn time. A key reaches the server only if you provide it: your own HYATLAS_LLM_KEY, a plain-text HYATLAS_LLM_KEY_FILE, the llm_key secret saved by hermes memory setup, or a launcher or tool you run that posts it to POST /api/v1/llm/key from the same machine (kept in memory only). A Nous Portal API key, or the key of any OpenAI-compatible provider, works. Until a key arrives, /api/v1/status reports llm: "awaiting_key" and writes are stored without extraction; once a key arrives the catch-up loop extracts them (see HYATLAS_CATCHUP_EVERY), and /api/v1/status shows how many are still waiting as unextracted.

Neither the server nor its launcher reads another program's credential file. Earlier versions of the sample launcher read Hermes' auth.json; a program that opens another application's credentials and then calls the internet is what credential stealers do, and behaviour-based antivirus (Bitdefender, for one) can quarantine it together with every file it wrote. The extraction key is your own. HYATLAS_LLM_KEY_FILE takes a plain-text token file only, so it cannot be pointed at a JSON credential file.

Optional: a local memory model (Hy-Memory-30B-A3B). If you want extraction and consolidation to stay on your machine, Tencent's Hy-Memory-30B-A3B (Apache-2.0) is a good fit. It is trained for exactly this job, writing long-term memory: deciding what to keep and how new facts update old ones. Tencent's model card scores it level with large general models as a memory writer. It is a mixture-of-experts model with about 30B parameters in total and about 3B active per token, so it runs faster than its size suggests. It is heavy, though:

The model stays loaded the whole time, so on a 24–32 GB machine it takes most of the memory. Builds below 4 bits (Q2, Q1, TQ1, 4–9 GB) load on 12–16 GB of RAM, but they lose too much accuracy for memory writing: wrong facts and broken JSON.

Serve it from any OpenAI-compatible server and point HyAtlas at it. For example, with llama.cpp and a community GGUF:

llama-server -m Hy-Memory-30B-A3B-Q4_K_M.gguf --port 8080 -c 32768 --n-cpu-moe 48 --jinja --chat-template-kwargs '{"reasoning_effort":"no_think"}'

export HYATLAS_LLM_BASE="http://127.0.0.1:8080/v1"
export HYATLAS_LLM_MODEL="hy-memory"
export HYATLAS_LLM_KEY="local"   # any non-empty value; a local server ignores it

Notes:

• --n-cpu-moe keeps that many layers' experts in system RAM. Raise it until the model fits your VRAM, and lower it for speed.
• The model card runs it with reasoning_effort: "no_think". Set that on the server as shown, because HyAtlas does not send it per request.
• To try it without giving up a hosted model, set it as the fallback instead (HYATLAS_LLM_FALLBACK_BASE, HYATLAS_LLM_FALLBACK_MODEL). It then answers only when the primary fails.
• Consolidation prompts are several thousand tokens. On a mid-range desktop with the experts in RAM, expect minutes per consolidation call. That is fine for a background pass, but slower than a hosted model.
• It was trained on the Mem0, MemOS and Hy-Memory prompt formats. HyAtlas uses its own, so check a few consolidation passes before relying on it.

All configuration is via environment variables — the binary reads no settings from its command line:

The binary reads no settings from the command line. It answers only --version and --help; any other argument is refused instead of starting a second server.

Durations. Every duration setting (the HYATLAS_CONSOLIDATE_* intervals, HYATLAS_RAW_RETENTION, HYATLAS_CATCHUP_EVERY, HYATLAS_EPISODE_GAP, HYATLAS_NOW_EVERY, HYATLAS_INTENTION_TTL, HYATLAS_SNAPSHOT_EVERY) reads a value the same way. 15m or 6h is a Go duration, a bare number is seconds, and 0, off, false or no turns the feature off. An empty value uses the default. A value that is none of these logs a line and uses the default, so a typo never changes the schedule silently.

Snapshots. The server backs itself up: every HYATLAS_SNAPSHOT_EVERY it writes hyatlas-<UTC time>.zip of the whole data directory to HYATLAS_SNAPSHOT_DIR, pausing writes while it copies, and keeps the newest HYATLAS_SNAPSHOT_KEEP. To restore, stop the server, replace the data directory with a snapshot's contents, and start it again.

Stopping. Ctrl-C or SIGTERM stops the server cleanly: it finishes the requests in progress, waits up to 10 seconds for background extractions that writes just served, then writes the doc index and usage counts. Whatever extraction is still left is picked up by the catch-up loop on the next start. A hard kill skips all of this, so the Windows launcher (hyatlas-go.ps1 stop) and the Hermes plugin's stop on Windows call POST /api/v1/flush before they stop the process.

Model assets

The BGE-small model + the platform-matching onnxruntime shared library live in models/ (gitignored). For a plain build, the server reads them at runtime. For an embedded build, go:embed bundles them into the binary at compile time from cmd/hyatlas-go/models/ (copy the same files there before building), so the release binary (built with -tags embedded) needs no model folder at all.

Where a plain build looks (when HYATLAS_MODEL_DIR is unset), in order:

1. <cwd>/models (a checkout run from the repo root)
2. <exe dir>/models (the folder the binary sits in)
3. the installer's default: ~/.hyatlas/models, or %LOCALAPPDATA%\hyatlas\models on Windows

If HYATLAS_MODEL_DIR is set, that directory is the only one searched. A plain build without a model in the searched places refuses to start and names every directory it checked. An embedded build never searches these places: it unpacks the bundled model into a temporary directory at startup.

Directory layout (per platform):

Where to get them:

• Model: https://huggingface.co/Xenova/bge-small-en-v1.5/resolve/main/onnx/model.onnx (saved as bge-small-en-v1.5.onnx) and .../resolve/main/vocab.txt. The release workflow and the installer use these URLs.
• onnxruntime 1.28.1: the release archives that .github/workflows/release.yml downloads, onnxruntime-<platform>-1.28.1 from microsoft/onnxruntime releases. Take the lib/ file for your platform (onnxruntime.dll, libonnxruntime.so or libonnxruntime.dylib).

To regenerate the ONNX from the HuggingFace model, see scripts/export_bge_onnx.py.

Version pins (critical)

• onnxruntime_go v1.32.0 — declares ONNX API 28
• onnxruntime 1.28.1 shared library — must expose API 28
• The .data external weights resolve relative to the process CWD. The embedder chdirs to the model dir while it loads the model, then changes back.

What changed since v3.5.0

• Pure Go rewrite — single binary (about 160 MB embedded release), no Python venv, no zvec, no Kuzu, no FastAPI
• In-process BGE embeddings via onnxruntime-go (cgo) — no HTTP embed subprocess
• L4 Summary enabled — was dormant in v3.5
• L5 bitemporal graph (v4.1.0+) — every L5 relation carries its source L2 memory IDs plus a bitemporal timestamp; the /api/v1/graph-as-of?ts=<unix> endpoint lets you rewind the graph to any past moment.
• Mind Palace (v4.1.0+) — a temporal visualization of the L5 knowledge graph in the Hermes Desktop hyatlas pane. Its design is in plugins/hyatlas/desktop/SPEC.md. The Desktop app itself is not part of this repository.
• Living memory (v4.6.0–v4.7.x) — the Now page, L8 entity pages, usage learning, topic-clustered consolidation with drop reasons, guards and restore.
• Precision per fact (v4.8.0) — event dates and date-aware search, updates with counts, intention due dates, episode summaries, history on read, near-duplicate demotion, idle-time recency, and the localhost key hand-over that replaced reading auth.json.
• A stable floor (v5.0.0) — turns that were never extracted are caught up, forgetting mirrored from Hermes's memory tool, linked facts and recurring events under HYATLAS_RECONCILE, the current session's intentions first, one alias rule everywhere, a clean shutdown, and a faster, inverted-index search.
• Smarter recall (v4.9.0) — task experiences, schemas with evidence, long facts found by their sentences, an entity boost and graph-assisted recall, query-kind weighting, and an opt-in second reconcile call for local models.

API Reference

Base URL: http://127.0.0.1:19528

Method notes: the handlers read their parameters from the query string, the JSON body, or both. Where a method is shown, that is the one the Hermes plugin and the docs use. Some handlers also accept other methods, so check routes() in cmd/hyatlas-go/server.go if you depend on that. Every route is behind the Host/Origin guard described above.

README truncated. Continue reading on GitHub