Memory

Memory is how Horus carries what you have already learned about a codebase into future investigations. It stores durable claims — confirmed incident outcomes, decisions, contracts, and pitfalls — scoped to a project, and recalls the relevant authored claims when you build an agent packet. An investigation opens by recalling matching past incidents, and saves itself as a new memory when it finishes. horus changes and horus what-changed list past incidents in the code a change touches. Memory can be recalled offline and is project-isolated; when the repo is linked and you are logged in, memory syncs to Cloud automatically and privately. Team promotion is a separate explicit action.

The two-store model

Memory is built from two stores, kept behind a clean seam:

• The durable record — the source of truth. Each memory item (its claim, kind, scope, confidence, status, links, and full audit trail) is persisted in your local embedded store (~/.horus). This is what memory list shows, what syncs to Horus Cloud when the repo is linked, and what every other command reads.
• Recall — how items are found. To rank what is relevant to a hint, Horus uses a vector index that lives only on your machine (embeddings come from the local source-intelligence host when it is available, with a deterministic keyword fallback otherwise). Startup recall keeps its hint vectors in a separate #incident-hints partition of the same index. The deterministic record stays authoritative; recall only proposes which items are relevant.

How items get into memory

You manage stored items with horus memory list, horus memory pin <id> (float to the top of recall), and horus memory forget <id> (a reversible, audited soft-delete that excludes the item from recall). See the CLI reference for every option.

Recall at the start of an investigation

Before collecting runtime evidence, horus investigate checks this project's memory (investigation memories, confirmed outcomes, and incident-pattern claims) for earlier incidents that match. An exact match on a structured alert field (fingerprint, error code, workflow, or operation) counts directly, and a recorded environment, service, or field that disagrees rules a memory out. Otherwise the hint is scored against every hint each past incident was investigated under, combining two signals:

• Keyword coverage: code-shaped identifiers such as PAY_017 are kept exact, camelCase and snake_case names are split into stemmed words, and rarer terms count for more (IDF-weighted). A rare identifier shared with at most two stored hints matches on its own.
• Local embedding similarity: the source-intelligence host embeds the hint and compares it with the stored hint vectors. With no host, recall is keyword-only.

Up to three matches print before the investigation continues, each as Prior incident <id> [<environment>; <certainty>] with what matched, the report to reopen, and a first check; otherwise Horus prints Prior incidents: no relevant match. After evidence is collected, the saved report (startupRecall in JSON) marks a match contradicted when live evidence meets one of its recorded invalidating conditions; the line printed at startup does not show this. The first investigation after upgrading indexes existing memories for similarity, spending at most two seconds; anything not yet indexed is matched by keywords. Set HORUS_STARTUP_RECALL=off (or 0/false) to skip startup recall.

Past incidents in the code you change

horus changes and horus what-changed add a Past incidents in this code section: earlier saved investigations in this project whose top cause Horus rated likely or highly-likely and whose top three code seeds include a method or function the change modifies or removes. In horus changes each entry shows the date, hint, investigation id, the touched symbols, and the cause found then; horus what-changed lists the date, hint, and id. At most five are listed, newest first, one per distinct hint. JSON output adds relatedIncidents, and horus what-changed --push sends a redacted copy to Horus Cloud.

Shared team memory

The published CLI separates private Cloud storage from team sharing. Linking a repo and logging in turns on automatic private sync of memory items, links, and audit history, which also restores this project's incident memory and its reports on another linked machine. horus memory sync shows the sync state; --resolve <memoryId> --choice local|cloud settles a visible conflict and --restore <memoryId> deliberately restores a synced forgotten memory. horus memory promote <id> explicitly shares an authored claim with the team; confirmed-outcome items cannot be promoted. Cloud owns team records and promotion is one-way and idempotent.

horus memory sync --dry-run
horus memory sync
horus memory promote <id>
horus memory pull

horus memory pull refreshes a disposable local cache of team items. Attribution and confidence remain attached; recall embeds them locally and can use a stale cache offline. Embeddings never sync.

Linking items

Memory items can be connected with typed edges so related knowledge travels together. horus memory link <a> <b> --rel supersedes|contradicts|recurs-with authors an edge by hand, horus memory unlink removes it, and horus memory detect conservatively proposes recurrence and contradiction edges (use --dry-run to preview).

Honesty and staleness

Memory is honest about age. Recall derives a freshness decay at read time from how long ago an item was last verified — it does not silently trust old claims. Age decay lowers an item's freshness label (fresh → recent → aging → stale) and its rank. Separately, a symbol that changed underneath the item is surfaced as possibly-stale for display (drift, detected on pull) — this is never persisted. Pinned items still surface drift but are never auto-hidden.

Because the downgrade is computed at read time, it is never persisted by recall: the durable record only changes through explicit actions (add, confirm, forget, pin), each of which is written to the audit trail.

Accuracy: the eval loop

Horus measures whether it actually helps. Two signals converge into one local outcome-label set:

• horus memory confirm <id> records the strongest signal — a human verified that Horus pointed at the cause — as a yes label.
• horus feedback <id> --resolved yes|partly|no records a lighter verdict, including from agents and scripts in non-interactive mode.

horus memory accuracy then reports the measured hit-rate: how often Horus pointed at the cause, the yes/partly/no breakdown, and the count of investigations evaluated. Slice it with --days, --since <date>, --all, --source feedback|confirm, and --limit. By default it windows to the last 30 days (pass --all for the full retained history) so pre-fix historical labels don't drag the headline.

horus feedback <id> --resolved yes
horus memory confirm <id>
horus memory accuracy --days 30

Memory in agent packets

When you build an agent packet, Horus recalls the memory items relevant to that packet's project and seed and includes them as remembered context. Recall there is best-effort and fail-closed: a missing project or an unavailable store simply yields no memory section — it never blocks or changes the packet, and the remembered items remain context, never live evidence.