MemoGrafter schema

Understand the generated mg.schema.ts reference, the PostgreSQL objects it describes, and the boundary between MemoGrafter and application data.

Generated schema reference

npx memo-grafter init creates src/memo-grafter/mg.schema.ts. It is an auto-generated, read-only reference for the PostgreSQL extensions, tables, columns, constraints, and indexes required by the installed MemoGrafter version.

Do not edit this file manually. Re-run npx memo-grafter init after upgrading MemoGrafter to regenerate it, review the resulting diff, and commit it with your project.

terminal

npx memo-grafter init
npx memo-grafter migrate
npx memo-grafter doctor

Reference versus migration

mg.schema.ts describes the schema; importing the file does not create database objects.

npx memo-grafter migrate enables the required extensions and creates or updates MemoGrafter-owned database infrastructure.

npx memo-grafter doctor checks extensions, migration state, and required core tables without changing the database.

MemoGrafter migrations manage only MemoGrafter-owned objects. Keep application tables in your existing Prisma, Drizzle, SQL, or custom migration workflow.

Required PostgreSQL extensions

vector provides pgvector columns and similarity indexes for topic and memory embeddings.

pgcrypto provides UUID generation for memory, edge, and graft-registry rows.

Conversation and ingestion tables

mg_sessions stores human-friendly session labels, descriptions, tags, and timestamps.

mg_message_buffer stores ordered raw user and assistant messages for each session.

mg_segments records the message ranges, topic order, and drift score of detected topic segments.

mg_session_ingest_state stores the last successfully ingested message index so incremental ingestion can resume safely.

Topic graph tables

mg_topic_nodes stores topic summaries, embeddings, tags, provenance, ordering, fleet ownership, and suppression state.

mg_topic_edges connects topic nodes with temporal, semantic, reentry, and graft relationships plus their weights.

Structured memory tables

mg_memory_nodes stores atomic facts, insights, questions, tasks, and references with embeddings, confidence, provenance, tags, and lifecycle state.

mg_memory_edges stores semantic, conflict, update, and related relationships between memory nodes.

Lifecycle columns retain forgotten, decayed, superseded, conflict, and suppression information so normal recall can filter inactive memory while history remains inspectable.

Grafting and fleet tables

mg_graft_registry records the source session and source topic for copied topic nodes, preserving graft provenance.

mg_fleets stores metadata for multi-agent memory groups.

mg_fleet_agents registers worker agents, their sessions, and their unique color within a fleet.

Indexes and constraints

The generated schema also lists the indexes and constraints used for session ordering, lifecycle filtering, tags, fleet lookup, graft ownership, and vector similarity search.

Vector indexes accelerate similarity search over mg_topic_nodes.embedding and mg_memory_nodes.embedding.

Lifecycle indexes support active-topic and active-memory filtering.

Tag indexes support scoped topic and memory lookup.

Foreign keys connect segments, topic nodes, memory nodes, edges, fleets, and graft records.

Unique constraints prevent duplicate segments, duplicate topic ownership, fleet color collisions, and duplicate graft-registry ownership.

Operational guidance

Treat every mg_* table as MemoGrafter-owned infrastructure.

Use supported APIs and lifecycle operations instead of directly mutating graph or memory rows.

Back up MemoGrafter tables according to the same recovery policy as the application data that depends on them.

Run migration as an intentional installation, upgrade, or deployment step rather than on every application request.

Review regenerated schema changes before deploying a new MemoGrafter version.