helixir-memory

Helixir memory

Treat Helixir as persistent, reasoning-aware memory shared by agents. Recall before re-deriving, and capture durable decisions at the moment they are made.

Establish identity

Choose one stable identity before the first call:

1. Use the principal configured by the host, normally HELIXIR_RBAC_ACTOR (claude, codex, or cursor after onboarding).
2. Otherwise use an explicitly assigned agent name, then the OS user as a last resort.
3. Use the same lower-case value as actor_id on every tool that accepts it.
4. Use one stable user_id for memory ownership. It may equal actor_id, but it is not an authorization credential.
5. If identity is uncertain, read the onboarding/client configuration or ask the operator. Only a global admin may use list_users; never silently adopt another principal.

Recall, work, capture

At the start of every non-trivial request, and immediately after a summary or context compaction, call:

search_memory(query="<current topic>", user_id="<stable owner>", actor_id="<principal>")

If personal recall is empty, retry once with scope="collective". Use mode="full" when an expected older fact is absent.

Store decisions, constraints, preferences, goals, outcomes, and hard-won gotchas with add_memory. Do not store secrets, ephemeral chatter, or facts trivially derivable from code or git.

Interpret write results exactly:

• ok:true is success and must not be retried.
• Non-empty updated contains ids of existing memories changed by the decision matrix.
• memories_added:0 plus non-empty deduped means already known.
• status:"accepted" plus pending_id means buffered success; poll with get_add_status only when the outcome is needed immediately.
• needs_clarification means the charter refused a silent conflict. Ask the suggested question or apply an established standing rule.
• Only ok:false or status:"failed" is failure.

Presence is explicit: transport initialization and ordinary reads never create or refresh a lease. A root agent, worker, or sub-agent calls agent_heartbeat immediately on start and at meaningful progress boundaries, using its stable logical actor_id plus a concrete agent_id; writes carrying that agent_id refresh the same lease. One-shot agents call agent_farewell(actor_id, agent_id) when done; that terminal status remains inactive until another explicit heartbeat or attributed write, while the heartbeat window is the crash and idle fallback.