Organization memory

An organization’s memory is one graph that every member’s agent searches alongside the member’s own memory. It holds what the whole team should know: conventions, decisions, architecture, customers, project history.

How recall uses it

When a member’s agent calls hm_recall, HyperMemory searches two graphs in parallel — the member’s own and the organization’s — with the same query. The answer keeps them apart:

• results — the member’s own memory.
• organization_memory — the organization’s results, labelled with its name.

A failure in the organization search never fails the member’s own recall: organization_memory.status is failed and the member’s results are still returned.

organization_memory.status	Meaning
included	The organization’s results are attached.
selection_required	The member belongs to several organizations and didn’t say which.
excluded	The agent sent organization_id: "none".
selected_graph	The credential’s own graph is the organization’s graph, so results already are its memory.
failed	The organization search failed; the member’s own results are still valid.

Reading it directly

hm_get_nodes, hm_find_related, hm_get_overview and hm_list_orphans take organization_id to read the organization’s graph instead of your own. The result carries read_target naming the organization and graph.

It’s read-only for members

No member — admin or user — writes to the organization graph by accident. Agents never choose to write there. The only way in is organization write mode.

Organization write mode

An owner or org admin can switch on organization write mode on Org → Memory. While it’s on, that admin’s writes go to the organization’s graph instead of their own:

Goes to the organization graph	Stays with the admin
hm_store, hm_update, hm_forget, hm_add_relationships, hm_ingest, hm_upload_file, hm_list_orphans	All reads (including hm_recall), hm_timeline_write, hm_tokens, usage and plan allowances

Each write’s result carries write_target, so the agent can say where the memory went.

• Write mode is off by default, and on in at most one organization at a time.
• It can only be switched from a signed-in dashboard session — never by an API key, OAuth token or agent.
• If the admin is demoted or removed, it switches off. If it’s on but the admin can no longer write the organization’s graph, writes are refused (organization_write_mode_not_permitted) — never silently sent to the admin’s personal graph.

Binding a project to an organization

If you belong to one organization, there’s nothing to do: it’s always searched.

If you belong to several, each project is bound to one of them — or to none — so recall searches the right one. Bindings live in ~/.config/hypermemory/projects.json, shared by the plugins and the CLI:

{
  "version": 1,
  "projects": {
    "/Users/alex/code/checkout": {
      "organization_id": "org_8c1f2a90d4e34b7f9a6e0c5b21d7f3aa",
      "name": "Acme"
    },
    "/Users/alex/code/side-project": {
      "organization_id": "none",
      "name": "none, personal memory only"
    }
  }
}

• A project is the repository’s main working tree, so all its git worktrees share one binding. Outside git, it’s the working directory.
• The plugins ask you the first time you open an unbound project and save your answer.
• With the CLI: hm org list, hm org use ORG_ID|none, hm org show, hm org clear. See CLI.
• In clients without plugins, tell the agent which organization to use; it sends that as organization_id.