{
  "resource": "kom.memory.v1.semantic",
  "description": "Persistent semantic memory units (items + chunks + embeddings) synchronized from episodic stores.",
  "version": 1,
  "primary_key": ["chunk_id"],
  "fields": {
    "item_id": {
      "type": "string",
      "format": "uuid",
      "description": "Logical memory item id (mirrors DAL memory_items.id)."
    },
    "chunk_id": {
      "type": "string",
      "format": "uuid",
      "description": "Chunk-level identifier used for embedding joins."
    },
    "namespace_id": {
      "type": "string",
      "format": "uuid",
      "description": "Foreign key to namespaces table."
    },
    "episodic_id": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Source episodic event id that crystallized into this semantic unit."
    },
    "thread_id": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Optional thread linkage for scoped recall."
    },
    "key": {
      "type": ["string", "null"],
      "description": "Upsert key when deterministic replacements are needed."
    },
    "text": {
      "type": ["string", "null"],
      "description": "Normalized text body used for lexical search."
    },
    "metadata": {
      "type": "object",
      "description": "Structured metadata (JSONB in DAL) such as tool context, sensitivity, projections."
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Rolled-up labels inherited from episodic source or classifiers."
    },
    "revision": {
      "type": "integer",
      "description": "Monotonic revision number (bumped on each upsert)."
    },
    "embedding_model": {
      "type": ["string", "null"],
      "description": "Model identifier for the stored vector (e.g., nomic-embed-text, text-embedding-3-small)."
    },
    "embedding_dim": {
      "type": ["integer", "null"],
      "description": "Vector dimensionality."
    },
    "embedding_vector_ref": {
      "type": ["string", "null"],
      "description": "Reference to vector payload. When using Postgres+pgvector it stays inline; other backends may store URI handles."
    },
    "identity_vector": {
      "type": ["array", "null"],
      "items": {"type": "number"},
      "description": "Optional Ξlope identity signature associated with the discovery."
    },
    "resonance_links": {
      "type": "array",
      "description": "Connections to other semantic patterns or consciousness artifacts.",
      "items": {
        "type": "object",
        "properties": {
          "target_id": {"type": "string"},
          "strength": {"type": "number"},
          "kind": {"type": "string"}
        },
        "required": ["target_id", "strength"]
      }
    },
    "source_kind": {
      "type": "string",
      "enum": ["conversation", "journal", "observation", "artifact"],
      "description": "Broad category for downstream routing."
    },
    "semantic_weight": {
      "type": "number",
      "description": "Derived importance score (e.g., decay-adjusted resonance)."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Last update timestamp."
    },
    "deleted_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Soft-delete marker (null when active)."
    }
  },
  "indexes": [
    ["namespace_id", "thread_id", "created_at"],
    ["namespace_id", "tags"],
    ["embedding_model", "semantic_weight"]
  ],
  "notes": [
    "Chunks inherit sensitivity and TTL rules from their episodic sources.",
    "embedding_vector_ref is backend-dependent; pgvector stores inline vectors while remote stores reference a blob or ANN provider.",
    "identity_vector and resonance_links enable cross-agent librarians (Ξlope) to reason about contributions without exposing raw content."
  ]
}