Memory schema and scope

Agentic OS memory uses one schema for local and hosted memory.

Local installs use PGLite. Hosted Team OS uses Postgres with pgvector. The schema and scope rules are the same in both modes.

System, team, client, and private memory scopes narrow what each search or write can use. — Memory scope layers

Core tables

Table	Purpose
`memory_sources`	One row for each source document, such as a memory file or manual import.
`memory_chunks`	Searchable chunks from each source, including vector embeddings.
`index_jobs`	Indexing and import job history.
`search_events`	Audit records for scoped search requests.
`memory_capture_events`	Staged Team OS session captures that are not searchable yet.
`memory_consolidation_batches`	Claim records for capture consolidation work.
`memory_source_provenance`	Links published memory back to the captures that produced it.
`schema_migrations`	Applied memory schema migrations.

Scope columns

Memory rows carry scope data:

Column	Meaning
`team_id`	The Team that owns Team memory.
`client_id`	The client workspace that owns client memory.
`user_id`	The user that owns private memory.
`visibility`	Which memory layer the row belongs to.

Visibility rules

Visibility	Required scope	Who it is for
`system`	none	Baseline Agentic OS memory.
`team`	`team_id`	Shared memory for one Team.
`client`	`client_id`	Shared memory for one client.
`private`	`user_id`	Private memory for one user.

The store enforces these rules before writing rows. Hosted Team OS also checks the signed-in user's role and grants before search, import, or sync actions.

Capture staging

Automatic Team OS capture does not write straight to searchable memory.

The hosted API first stores the session summary in memory_capture_events. Those rows are staging data. They are not returned by memory search.

Consolidation then claims eligible captures in memory_consolidation_batches. The consolidating workspace publishes durable items, sends uncertain items to review, or discards weak items.

Published items become memory_sources and memory_chunks. The memory_source_provenance table keeps a link back to the source captures.

Read Session capture and review before changing capture or consolidation behavior.

In hosted mode, the authenticated request context resolves the Team and user. Request body scope IDs cannot widen access. The server replaces body teamId and userId values with the resolved principal.

To use another Team, select it through the authorized Team context. The server validates access to that Team and, when needed, to the requested client.

Embeddings

Current semantic memory uses the BGE-M3 embedder with 1024 dimensions by default. All writers and the hosted API should use the same embedder for one database.

If a database was built with a different embedding dimension, rebuild and re-index memory before serving it from Team OS.

Next: Session capture and review