Multi-project memory

Every repository keeps its own graph — and since v0.6 they're aware of each other, through one core process per machine. The design principle is access, not replication: any project can read the others' graphs, so nothing needs syncing, and one insight lives in exactly one graph.

One core, one pane

engram-alpha serve is safe to run from anywhere, as many times as you like:

• serve is a launcher, not a server: it makes sure the machine core is running (starting it detached when the machine has none), registers your current repository with it, prints the pane URL, and exits — the core keeps serving. Ten concurrent serve runs converge on exactly one core process on one port — never a second pane.
• From a git repository without a graph, it asks before creating one — nothing is initialized silently. (You can also add any folder later from the pane's project picker.)
• From your home directory or any non-git folder, it just ensures the core — which always holds the home graph — useful when you only want the pane.

The pane's top-bar switcher moves between projects; every project's live updates stream to the same UI.

engram-alpha stop shuts down the core and every satellite process in one gesture — used before updates, or whenever a repair needs exclusive access to the stores.

The registry

Each serve, mcp, or setup run registers its repository in ~/.engram/registry.json — plain JSON, inspectable with cat. The registry is how projects find each other and how the pane's project list is built. Removing an entry (pane: Settings → System → forget) never touches the project's graph; it only forgets the address.

Settings → System describes the core itself, so its store health (size, integrity, vectors) is the home graph's. Pick another project in the switcher and the panel names that project's folder and database file instead.

The home graph

~/.engram/home.tepin is a normal Engram graph for knowledge that was never project-scoped: your global principles, standing preferences, cross-cutting cautions. Its canon rides along in every project's session brief. Tell your assistant "remember this globally" and it lands there.

When the same Principle or Caution shows up in several project graphs, a Checkup pass nominates it for promotion into the home graph — the copy moves up, the projects keep provenance links, and as everywhere in Engram: the scan nominates, you approve.

What the assistant sees

An assistant session is bound to the repository it runs in — its searches and writes go to that project's graph by default. Most MCP tools also take an optional project:

• omit it → the current repository
• a project name (or its id, or its folder — any path inside the repo) → that project's graph, reads and writes — an insight about a sibling project belongs in that project's memory. A folder is what scripts and hooks usually have: GET /brief?project=/path/to/repo is how the session-start hook asks the core for the right brief
• home → the shared home graph
• all → read across everything (search and claim checks only). Foreign hits carry provenance and rank under a locality prior, so the local canon wins ties. Writes to all are refused by design — fanning one write into N graphs would mint N future duplicates.

How it works underneath

The core process is the sole owner of every open store; assistants connect through lightweight bridges that follow the core — they reconnect when it restarts and exit when it stays gone (no orphan processes), and the session brief and doctor read through it the same way. This matters most on the TepinDB backend, whose single-file stores allow exactly one owning process — the core is that process, for all of them. The full picture — process roles, discovery, leases, idle unload, and the shutdown sequence — is on Runtime architecture; engram-alpha status shows it live.