Project and global memory#

A project decision belongs with its project. A personal preference may apply across projects. Ormah uses a space label for that distinction, while keeping memories in one store.

Choose the right scope#

Global does not mean always injected. Retrieval still checks relevance, and the preference channel checks applicability to the current task. A package-manager preference can matter when installing dependencies without answering an unrelated question about checkout retries.

How a space is chosen#

CLI/MCP detection prefers a nonempty explicit value, then ORMAH_SPACE, then the repository root basename or working-directory basename. Home/root directories do not automatically become a space. Client hooks/extensions pass their own session/project context; check what actually reaches the server.

ormah remember "This project uses pnpm for package management." --type preference --space ormah-demo
ormah recall "Which package manager does this project use?" --space ormah-demo

--space on CLI recall is a ranking preference, not a strict filter. With the memory tools or HTTP API, spaces: ["ormah-demo"] restricts results to those labels. Other-space memories may otherwise appear at a lower rank. Spaces are organizational labels, not access-control boundaries; two repositories with the same basename can share a label.

To override detection for a CLI-launched agent, set ORMAH_SPACE=ormah-demo in the environment that launches the integration. A GUI-launched app might not inherit your shell environment. Inspect the saved node's space and the client request rather than assuming the override applied.

Save a global memory reliably#

The MCP adapter adds its detected default space. A tool call with space: null can therefore fall back to the project, even if its guidance describes null as global.

For an unambiguous global write, use HTTP with space: null and no default_space query parameter. This synthetic example uses a preference only for demonstration; delete it afterward if it isn't yours.

curl -fsS http://127.0.0.1:8787/agent/remember \
  -H 'Content-Type: application/json' \
  -d '{"content":"Synthetic global preference: use metric units in examples.","type":"preference","tier":"working","space":null,"tags":["synthetic-test"]}'

Open the returned node in the graph and check its actual stored space is global. Do not treat an agent's description of scope as proof. For an existing node, the update endpoint treats both omitted space and space: null as “leave unchanged.” It can set a named space, but cannot clear scope to null. The graph has no editor. To retain the same node ID while making it global, follow the controlled offline source-edit procedure: change the Markdown frontmatter's space to null, restart and verify the indexed value. Do not assume a successful update response proves the scope changed.

Share across agents#

Use the same service/store and matching project context. The Codex → Ormah → Claude illustration shares one local store; it does not copy memories between machines. On another machine, use the supported backup and recovery path rather than assuming device synchronization.

For deeper ranking behavior see Search and ranking. To correct content or remove a synthetic test, see Inspect your memory.