---
description: Choose project scope, save a global memory reliably, and understand shared-store boundaries.
---

# 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

| Memory | Scope | Example |
| --- | --- | --- |
| A project decision | Named space | “Checkout retries must reuse the same idempotency key.” in `ormah-demo` |
| A project preference | Named space, type `preference` | “This project uses pnpm for package management.” |
| A personal preference | Global (`space: null` in stored data) | A preference that should be considered across your projects |

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.

```bash
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.

```bash
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](/docs/how-ormah-works/storage-layer#editing-and-moving-files): 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](/docs/use-memory/backup-and-recovery) path rather than assuming device synchronization.

For deeper ranking behavior see [Search and ranking](/docs/how-ormah-works/search-and-ranking). To correct content or remove a synthetic test, see [Inspect your memory](/docs/reference/web-ui).