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. During an investigation it recalls similar past incidents (incident memory) and auto-captures a new memory, rather than surfacing authored claims. Memory is offline and project-isolated.

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 memory sync can push to Horus Cloud, 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). 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.

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.