{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://plur.ai/spec/v1/engram.schema.json",
  "title": "Engram",
  "description": "An engram is the atomic unit of learned knowledge in the Open Engram Standard v1. Generated from the Zod EngramSchema in @plur-ai/core (packages/core/src/schemas/engram.ts) by packages/core/scripts/gen-spec-schemas.ts — do not edit by hand. See ENGRAM-STANDARD-v1.md for normative semantics.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^(ENG|ABS|META)-[A-Za-z0-9-]+$",
      "description": "Unique identifier. Class prefix ENG (concrete engram), ABS (abstraction), or META (meta-engram). Canonical concrete form: ENG-YYYY-MMDD-NNN; store-namespaced form: ENG-{PREFIX}-YYYY-MMDD-NNN."
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "default": 2,
      "description": "Schema-shape generation of this engram object (currently 2). Distinct from engram_version, which tracks content evolution."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "dormant",
        "retired",
        "candidate"
      ],
      "description": "Lifecycle state."
    },
    "consolidated": {
      "type": "boolean",
      "default": false,
      "description": "Whether this engram has been through consolidation (sleep-like batch reprocessing)."
    },
    "type": {
      "type": "string",
      "enum": [
        "behavioral",
        "terminological",
        "procedural",
        "architectural"
      ],
      "description": "Top-level classification of the knowledge."
    },
    "scope": {
      "type": "string",
      "description": "Hierarchical namespace, e.g. 'global', 'project:my-app', 'group:plur/test'. Free-form string; ':' separates scope kind from path."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public",
        "template"
      ],
      "default": "private",
      "description": "Sharing posture. 'private' engrams MUST NOT be exported in packs."
    },
    "statement": {
      "type": "string",
      "minLength": 1,
      "description": "The assertion itself — the load-bearing content of the engram."
    },
    "rationale": {
      "type": "string",
      "description": "Why this is true / why it matters."
    },
    "contraindications": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Conditions under which the statement does NOT apply."
    },
    "source": {
      "type": "string",
      "description": "Free-text origin (session, document, conversation)."
    },
    "source_patterns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Pattern IDs that contributed to this engram."
    },
    "derivation_count": {
      "type": "integer",
      "minimum": 0,
      "default": 1,
      "description": "How many derivation steps produced this engram."
    },
    "pack": {
      "type": [
        "string",
        "null"
      ],
      "default": null,
      "description": "Name of the pack this engram belongs to, or null."
    },
    "abstract": {
      "type": [
        "string",
        "null"
      ],
      "default": null,
      "description": "ID of an ABS- abstraction this engram instantiates, or null."
    },
    "derived_from": {
      "type": [
        "string",
        "null"
      ],
      "default": null,
      "description": "ID of the engram this was derived from, or null."
    },
    "knowledge_type": {
      "type": "object",
      "properties": {
        "memory_class": {
          "type": "string",
          "enum": [
            "semantic",
            "episodic",
            "procedural",
            "metacognitive"
          ]
        },
        "cognitive_level": {
          "type": "string",
          "enum": [
            "remember",
            "understand",
            "apply",
            "analyze",
            "evaluate",
            "create"
          ],
          "description": "Bloom's taxonomy level."
        }
      },
      "required": [
        "memory_class",
        "cognitive_level"
      ],
      "additionalProperties": false
    },
    "domain": {
      "type": "string",
      "description": "Dotted domain path, e.g. 'dev/testing' or 'plur.session'."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": [],
      "description": "Free-form tags used for matching and retrieval."
    },
    "activation": {
      "type": "object",
      "properties": {
        "retrieval_strength": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "storage_strength": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "frequency": {
          "type": "integer",
          "minimum": 0
        },
        "last_accessed": {
          "type": "string",
          "description": "Date or ISO 8601 timestamp of last access."
        }
      },
      "required": [
        "retrieval_strength",
        "storage_strength",
        "frequency",
        "last_accessed"
      ],
      "additionalProperties": false,
      "description": "ACT-R activation parameters driving decay and ranking. STABLE.",
      "default": {
        "retrieval_strength": 0.7,
        "storage_strength": 1,
        "frequency": 0,
        "last_accessed": ""
      }
    },
    "relations": {
      "type": "object",
      "properties": {
        "broader": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "narrower": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "related": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "conflicts": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "supersedes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "superseded_by": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        }
      },
      "additionalProperties": false,
      "description": "Typed graph edges between engram IDs."
    },
    "associations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "target_type": {
            "type": "string",
            "enum": [
              "engram",
              "document"
            ]
          },
          "target": {
            "type": "string",
            "description": "ID or path of the association target."
          },
          "strength": {
            "type": "number",
            "minimum": 0,
            "maximum": 0.95
          },
          "type": {
            "type": "string",
            "enum": [
              "semantic",
              "temporal",
              "causal",
              "co_accessed"
            ]
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "target_type",
          "target",
          "strength",
          "type"
        ],
        "additionalProperties": false
      },
      "default": []
    },
    "knowledge_anchors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to a grounding document/file."
          },
          "relevance": {
            "type": "string",
            "enum": [
              "primary",
              "supporting",
              "example"
            ],
            "default": "supporting"
          },
          "snippet": {
            "type": "string",
            "maxLength": 200
          },
          "snippet_extracted_at": {
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "additionalProperties": false
      },
      "default": []
    },
    "dual_coding": {
      "type": "object",
      "properties": {
        "example": {
          "type": "string"
        },
        "analogy": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "Worked example and/or analogy (dual coding). At least one of example or analogy MUST be provided (enforced at runtime by the Zod .refine below)."
    },
    "provenance": {
      "type": "object",
      "properties": {
        "origin": {
          "type": "string"
        },
        "chain": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "signature": {
          "type": [
            "string",
            "null"
          ],
          "default": null,
          "description": "RESERVED. Detached signature over the engram. Algorithm and canonicalization not yet specified — see ENGRAM-STANDARD-v1.md §7."
        },
        "license": {
          "type": "string",
          "default": "cc-by-sa-4.0"
        }
      },
      "required": [
        "origin"
      ],
      "additionalProperties": false,
      "description": "Origin and signing chain. STABLE for origin/chain/license; signature is RESERVED (see ENGRAM-STANDARD-v1.md §7)."
    },
    "feedback_signals": {
      "type": "object",
      "properties": {
        "positive": {
          "type": "integer",
          "default": 0
        },
        "negative": {
          "type": "integer",
          "default": 0
        },
        "neutral": {
          "type": "integer",
          "default": 0
        }
      },
      "additionalProperties": false,
      "default": {
        "positive": 0,
        "negative": 0,
        "neutral": 0
      }
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "person",
              "organization",
              "technology",
              "concept",
              "project",
              "tool",
              "place",
              "event",
              "standard",
              "other"
            ]
          },
          "uri": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "type"
        ],
        "additionalProperties": false
      },
      "description": "Typed entity references extracted from statement. Enables graph queries."
    },
    "temporal": {
      "type": "object",
      "properties": {
        "learned_at": {
          "type": "string"
        },
        "valid_from": {
          "type": "string"
        },
        "valid_until": {
          "type": "string"
        },
        "ingested_at": {
          "type": "string"
        }
      },
      "required": [
        "learned_at"
      ],
      "additionalProperties": false,
      "description": "Bi-temporal anchoring (Zep-inspired). When is this knowledge true?"
    },
    "usage": {
      "type": "object",
      "properties": {
        "injections": {
          "type": "integer",
          "default": 0
        },
        "hits": {
          "type": "integer",
          "default": 0
        },
        "misses": {
          "type": "integer",
          "default": 0
        },
        "last_hit_at": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "episodic": {
      "type": "object",
      "properties": {
        "emotional_weight": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "default": 5
        },
        "confidence": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "default": 5
        },
        "trigger_context": {
          "type": "string"
        },
        "journal_ref": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "exchange": {
      "type": "object",
      "properties": {
        "fitness_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "environmental_diversity": {
          "type": "integer",
          "default": 0
        },
        "adoption_count": {
          "type": "integer",
          "default": 0
        },
        "contradiction_rate": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0
        }
      },
      "additionalProperties": false
    },
    "structured_data": {
      "type": "object",
      "additionalProperties": {},
      "description": "Extensible key-value data for domain-specific fields."
    },
    "insight": {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "enum": [
            "distill",
            "consolidate",
            "dream",
            "connect",
            "emerge",
            "drift"
          ]
        },
        "synthesized_at": {
          "type": "string"
        },
        "grounding": {
          "type": "string",
          "enum": [
            "verified",
            "unverified",
            "ungrounded",
            "speculative"
          ],
          "default": "unverified"
        },
        "source_episode_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "serendipity": {
          "type": "object",
          "properties": {
            "unexpectedness": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "relevance": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "score": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "unexpectedness",
            "relevance",
            "score"
          ],
          "additionalProperties": false
        },
        "fate": {
          "type": "string",
          "enum": [
            "surfaced",
            "promoted",
            "cited",
            "tasked",
            "dismissed",
            "expired"
          ],
          "default": "surfaced"
        },
        "fate_ref": {
          "type": "string"
        },
        "fate_at": {
          "type": "string"
        },
        "surfaced_count": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "required": [
        "operation",
        "synthesized_at"
      ],
      "additionalProperties": false
    },
    "polarity": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "do",
            "dont"
          ]
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "'do' for directives, 'dont' for prohibitions, null for unclassified."
    },
    "content_hash": {
      "type": "string",
      "description": "Hash of normalized statement content, used for dedup."
    },
    "commitment": {
      "type": "string",
      "enum": [
        "exploring",
        "leaning",
        "decided",
        "locked"
      ],
      "description": "Commitment level of the asserted knowledge."
    },
    "locked_at": {
      "type": "string",
      "description": "Timestamp when commitment reached 'locked'."
    },
    "locked_reason": {
      "type": "string",
      "description": "Why this engram was locked."
    },
    "reference_count": {
      "type": "integer",
      "minimum": 0,
      "default": 1,
      "description": "Number of write attempts that resolved to this engram (same-scope re-learns). Engram retires only when this reaches 0."
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string"
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ],
            "default": null
          },
          "stored_at": {
            "type": "string",
            "description": "ISO 8601 timestamp of this write."
          }
        },
        "required": [
          "scope",
          "stored_at"
        ],
        "additionalProperties": false
      },
      "default": [],
      "description": "Provenance of each write attempt; one entry per write."
    },
    "recurrence_count": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Number of times this content was re-learned at a DIFFERENT scope than the original. Evidence of universal applicability."
    },
    "engram_version": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Content-evolution version (incremented when the statement materially changes)."
    },
    "previous_version_ref": {
      "type": "object",
      "properties": {
        "event_id": {
          "type": "string"
        },
        "changed_at": {
          "type": "string"
        }
      },
      "required": [
        "event_id",
        "changed_at"
      ],
      "additionalProperties": false
    },
    "episode_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": [],
      "description": "IDs of episodes (raw conversational events) that produced or reinforced this engram."
    },
    "summary": {
      "type": "string",
      "maxLength": 80,
      "description": "Short (<=80 char) injection-friendly summary."
    },
    "pinned": {
      "type": "boolean",
      "description": "Always-load flag. Pinned engrams bypass the keyword-relevance gate and are eligible for injection every session. Use sparingly."
    }
  },
  "required": [
    "id",
    "status",
    "type",
    "scope",
    "statement"
  ],
  "additionalProperties": true
}