@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/apis/memorix-records/overview.md

@@ -0,0 +1,22 @@
+---
+id: "memorix-records"
+type: "api"
+title: "Memorix records API"
+summary: "Read and conditionally write Memorix records with revision preconditions."
+why: "Agents and services need exact revision-safe operations."
+---
+# Memorix records API
+
+Read and conditionally write Memorix records with revision preconditions.
+
+## Why
+
+Agents and services need exact revision-safe operations.
+
+## GET /api/records/{id}
+
+Read a record envelope and content.
+
+## PATCH /api/records/{id}
+
+Conditionally update a record with expected revision.

package/files/concepts/abstracts-bindings.md

@@ -0,0 +1,27 @@
+---
+id: "abstracts-bindings"
+type: "concept"
+title: "Abstracts and bindings"
+summary: "An abstract is a virtual union projected through bindings — not stored rows."
+problem: "Callers otherwise duplicate union queries across concrete types."
+why: "Abstracts give stable read models without denormalizing storage."
+mentalModel: "Bindings map concrete members into an abstract projection."
+audiences: ["developers", "builders"]
+related: ["people-union"]
+next: ["people-union"]
+---
+# Abstracts and bindings
+
+An abstract is a virtual union projected through bindings — not stored rows.
+
+## Problem
+
+Callers otherwise duplicate union queries across concrete types.
+
+## Why
+
+Abstracts give stable read models without denormalizing storage.
+
+## Mental model
+
+Bindings map concrete members into an abstract projection.

package/files/concepts/agents-inheritance.md

@@ -0,0 +1,28 @@
+---
+id: "agents-inheritance"
+type: "concept"
+title: "Agents and inheritance"
+summary: "Child agents inherit definitions; Studio shows the effective result."
+problem: "Reading only local files hides parent contributions and conflicts."
+why: "Inheritance keeps shared definitions DRY while allowing replacement and additive behavior."
+mentalModel: "Oldest-parent-first resolution into an effective model."
+audiences: ["developers", "builders"]
+prerequisites: ["org-agent-scope"]
+related: ["effective-metadata"]
+next: ["effective-metadata"]
+---
+# Agents and inheritance
+
+Child agents inherit definitions; Studio shows the effective result.
+
+## Problem
+
+Reading only local files hides parent contributions and conflicts.
+
+## Why
+
+Inheritance keeps shared definitions DRY while allowing replacement and additive behavior.
+
+## Mental model
+
+Oldest-parent-first resolution into an effective model.

package/files/concepts/analysis-objects.md

@@ -0,0 +1,26 @@
+---
+id: "analysis-objects"
+type: "concept"
+title: "Analysis objects"
+summary: "Analysis captures evaluated evidence distinct from operational decisions."
+problem: "Mixing analysis with decisions hides how conclusions formed."
+why: "Separating analysis keeps auditability and replay."
+mentalModel: "Evidence → analysis → (later) decision."
+audiences: ["developers", "builders"]
+related: ["decisions-content", "intelligence-proposals"]
+---
+# Analysis objects
+
+Analysis captures evaluated evidence distinct from operational decisions.
+
+## Problem
+
+Mixing analysis with decisions hides how conclusions formed.
+
+## Why
+
+Separating analysis keeps auditability and replay.
+
+## Mental model
+
+Evidence → analysis → (later) decision.

package/files/concepts/composition.md

@@ -0,0 +1,27 @@
+---
+id: "composition"
+type: "concept"
+title: "Same-subject composition"
+summary: "Multiple content instances can belong to one subject when composition is explicit."
+problem: "Callers otherwise assume one row per subject."
+why: "Subjects accumulate history and alternate content types."
+mentalModel: "Subject → composed bag of content instances."
+audiences: ["developers", "builders"]
+prerequisites: ["raw-records"]
+related: ["people-union"]
+---
+# Same-subject composition
+
+Multiple content instances can belong to one subject when composition is explicit.
+
+## Problem
+
+Callers otherwise assume one row per subject.
+
+## Why
+
+Subjects accumulate history and alternate content types.
+
+## Mental model
+
+Subject → composed bag of content instances.

package/files/concepts/decisions-content.md

@@ -0,0 +1,27 @@
+---
+id: "decisions-content"
+type: "concept"
+title: "Decisions"
+summary: "Decisions record chosen actions distinct from analysis content."
+problem: "If decisions are only implied in chats, systems cannot act reliably."
+why: "Durable decisions drive workflows and audits."
+mentalModel: "Analysis informs; decision commits."
+audiences: ["developers", "builders"]
+prerequisites: ["analysis-objects"]
+related: ["intelligence-proposals"]
+---
+# Decisions
+
+Decisions record chosen actions distinct from analysis content.
+
+## Problem
+
+If decisions are only implied in chats, systems cannot act reliably.
+
+## Why
+
+Durable decisions drive workflows and audits.
+
+## Mental model
+
+Analysis informs; decision commits.

package/files/concepts/effective-metadata.md

@@ -0,0 +1,27 @@
+---
+id: "effective-metadata"
+type: "concept"
+title: "Effective metadata"
+summary: "The resolved definitions after inheritance and installation."
+problem: "Authors confuse source files with what the runtime actually uses."
+why: "Readers and writers must see the effective model before mutating data."
+mentalModel: "Installed + inherited → effective."
+audiences: ["developers", "builders"]
+prerequisites: ["explicit-metadata-installation", "agents-inheritance"]
+related: ["org-agent-scope"]
+---
+# Effective metadata
+
+The resolved definitions after inheritance and installation.
+
+## Problem
+
+Authors confuse source files with what the runtime actually uses.
+
+## Why
+
+Readers and writers must see the effective model before mutating data.
+
+## Mental model
+
+Installed + inherited → effective.

package/files/concepts/explicit-metadata-installation.md

@@ -0,0 +1,26 @@
+---
+id: "explicit-metadata-installation"
+type: "concept"
+title: "Explicit metadata validation and installation"
+summary: "Validation does not install; installation requires confirmation."
+problem: "Auto-applying packs or proposals would silently change runtime behavior."
+why: "Reviewable, deterministic, reversible configuration changes."
+mentalModel: "Treat metadata packs like deployments."
+audiences: ["builders", "developers"]
+related: ["intelligence-proposals", "effective-metadata"]
+---
+# Explicit metadata validation and installation
+
+Validation does not install; installation requires confirmation.
+
+## Problem
+
+Auto-applying packs or proposals would silently change runtime behavior.
+
+## Why
+
+Reviewable, deterministic, reversible configuration changes.
+
+## Mental model
+
+Treat metadata packs like deployments.

package/files/concepts/intelligence-proposals.md

@@ -0,0 +1,27 @@
+---
+id: "intelligence-proposals"
+type: "concept"
+title: "Intelligence proposals"
+summary: "Intelligence may propose metadata or actions but never auto-installs them."
+problem: "Silent installation would violate reviewability."
+why: "Humans remain the confirmation boundary for runtime-changing packs."
+mentalModel: "Propose → review → explicit install or reject."
+audiences: ["builders", "developers"]
+prerequisites: ["explicit-metadata-installation"]
+related: ["explicit-metadata-installation"]
+---
+# Intelligence proposals
+
+Intelligence may propose metadata or actions but never auto-installs them.
+
+## Problem
+
+Silent installation would violate reviewability.
+
+## Why
+
+Humans remain the confirmation boundary for runtime-changing packs.
+
+## Mental model
+
+Propose → review → explicit install or reject.

package/files/concepts/mappings-transforms.md

@@ -0,0 +1,26 @@
+---
+id: "mappings-transforms"
+type: "concept"
+title: "Mappings and transforms"
+summary: "Mappings describe how source shapes become Memory content."
+problem: "Ad-hoc transforms hide field provenance."
+why: "Explicit mappings make validation and recovery possible."
+mentalModel: "Declared mapping, not implicit guesswork."
+audiences: ["developers"]
+related: ["raw-records"]
+---
+# Mappings and transforms
+
+Mappings describe how source shapes become Memory content.
+
+## Problem
+
+Ad-hoc transforms hide field provenance.
+
+## Why
+
+Explicit mappings make validation and recovery possible.
+
+## Mental model
+
+Declared mapping, not implicit guesswork.

package/files/concepts/object-content-category.md

@@ -0,0 +1,26 @@
+---
+id: "object-content-category"
+type: "concept"
+title: "Object type, content type, and data category"
+summary: "Identity, payload shape, and category are separate axes."
+problem: "Collapsing them forces brittle one-size schemas."
+why: "Memorix needs the same subject to carry multiple content shapes over time."
+mentalModel: "Object identity × content type × category."
+audiences: ["developers"]
+related: ["raw-records", "composition"]
+---
+# Object type, content type, and data category
+
+Identity, payload shape, and category are separate axes.
+
+## Problem
+
+Collapsing them forces brittle one-size schemas.
+
+## Why
+
+Memorix needs the same subject to carry multiple content shapes over time.
+
+## Mental model
+
+Object identity × content type × category.

package/files/concepts/org-agent-scope.md

@@ -0,0 +1,27 @@
+---
+id: "org-agent-scope"
+type: "concept"
+title: "Organization and agent scope"
+summary: "Scope selects which organization and agent context reads and writes apply to."
+problem: "Acting without explicit scope can touch the wrong workspace."
+why: "Memorix isolates tenants and agent inheritance behind deliberate scope selection."
+mentalModel: "Scope is a workspace lock, not decoration."
+audiences: ["developers", "builders"]
+related: ["agents-inheritance", "effective-metadata"]
+next: ["agents-inheritance"]
+---
+# Organization and agent scope
+
+Scope selects which organization and agent context reads and writes apply to.
+
+## Problem
+
+Acting without explicit scope can touch the wrong workspace.
+
+## Why
+
+Memorix isolates tenants and agent inheritance behind deliberate scope selection.
+
+## Mental model
+
+Scope is a workspace lock, not decoration.

package/files/concepts/people-union.md

@@ -0,0 +1,27 @@
+---
+id: "people-union"
+type: "concept"
+title: "People union"
+summary: "People combines employees and contractors through explicit bindings."
+problem: "UIs need one people list without merging tables by hand."
+why: "Abstract projection preserves concrete types while enabling combined reads."
+mentalModel: "employees ∪ contractors → People."
+audiences: ["developers", "builders"]
+prerequisites: ["abstracts-bindings"]
+related: ["composition"]
+---
+# People union
+
+People combines employees and contractors through explicit bindings.
+
+## Problem
+
+UIs need one people list without merging tables by hand.
+
+## Why
+
+Abstract projection preserves concrete types while enabling combined reads.
+
+## Mental model
+
+employees ∪ contractors → People.

package/files/concepts/raw-records.md

@@ -0,0 +1,26 @@
+---
+id: "raw-records"
+type: "concept"
+title: "Raw records"
+summary: "Raw retains the original payload beside envelope metadata."
+problem: "Losing raw makes audits and remapping impossible."
+why: "Memorix keeps evidence of what arrived."
+mentalModel: "Envelope + raw body; choose views deliberately."
+audiences: ["developers", "builders"]
+related: ["composition", "object-content-category"]
+---
+# Raw records
+
+Raw retains the original payload beside envelope metadata.
+
+## Problem
+
+Losing raw makes audits and remapping impossible.
+
+## Why
+
+Memorix keeps evidence of what arrived.
+
+## Mental model
+
+Envelope + raw body; choose views deliberately.

package/files/concepts/record-revisions.md

@@ -0,0 +1,26 @@
+---
+id: "record-revisions"
+type: "concept"
+title: "Record revisions and stale-write conflicts"
+summary: "Writes carry an expected revision; stale writers cannot overwrite newer data."
+problem: "Lost updates when concurrent writers race."
+why: "Revision preconditions preserve newer data and force explicit recovery."
+mentalModel: "Load → mutate → write with expected revision → reload on conflict."
+audiences: ["developers", "builders"]
+related: ["raw-records"]
+---
+# Record revisions and stale-write conflicts
+
+Writes carry an expected revision; stale writers cannot overwrite newer data.
+
+## Problem
+
+Lost updates when concurrent writers race.
+
+## Why
+
+Revision preconditions preserve newer data and force explicit recovery.
+
+## Mental model
+
+Load → mutate → write with expected revision → reload on conflict.

package/files/concepts/relationship-definitions.md

@@ -0,0 +1,26 @@
+---
+id: "relationship-definitions"
+type: "concept"
+title: "Relationship definitions"
+summary: "A relationship definition is metadata describing allowed links — not a stored edge on a record."
+problem: "Confusing definitions with instances breaks traversal expectations."
+why: "Definitions make forward/inverse traversal predictable."
+mentalModel: "Definition first; references second."
+audiences: ["developers"]
+related: ["relationship-references", "traversal"]
+---
+# Relationship definitions
+
+A relationship definition is metadata describing allowed links — not a stored edge on a record.
+
+## Problem
+
+Confusing definitions with instances breaks traversal expectations.
+
+## Why
+
+Definitions make forward/inverse traversal predictable.
+
+## Mental model
+
+Definition first; references second.

package/files/concepts/relationship-references.md

@@ -0,0 +1,27 @@
+---
+id: "relationship-references"
+type: "concept"
+title: "Stored relationship references"
+summary: "Records store relationship references that point at targets under a definition."
+problem: "Without stored refs, graphs cannot be rebuilt or verified."
+why: "References are the durable facts; definitions are the schema."
+mentalModel: "Record holds refs typed by definition id."
+audiences: ["developers"]
+prerequisites: ["relationship-definitions"]
+related: ["resolved-unresolved"]
+---
+# Stored relationship references
+
+Records store relationship references that point at targets under a definition.
+
+## Problem
+
+Without stored refs, graphs cannot be rebuilt or verified.
+
+## Why
+
+References are the durable facts; definitions are the schema.
+
+## Mental model
+
+Record holds refs typed by definition id.

package/files/concepts/resolved-unresolved.md

@@ -0,0 +1,27 @@
+---
+id: "resolved-unresolved"
+type: "concept"
+title: "Resolved and unresolved relationships"
+summary: "Unresolved targets are retained and shown — not silently dropped."
+problem: "Hiding unresolved links loses operational truth."
+why: "Operators need to repair, wait, or escalate deliberately."
+mentalModel: "Absence of a target is a first-class state."
+audiences: ["developers", "builders"]
+prerequisites: ["traversal"]
+related: ["relationship-references"]
+---
+# Resolved and unresolved relationships
+
+Unresolved targets are retained and shown — not silently dropped.
+
+## Problem
+
+Hiding unresolved links loses operational truth.
+
+## Why
+
+Operators need to repair, wait, or escalate deliberately.
+
+## Mental model
+
+Absence of a target is a first-class state.

package/files/concepts/sources-and-memory.md

@@ -0,0 +1,26 @@
+---
+id: "sources-and-memory"
+type: "concept"
+title: "Sources and Memory"
+summary: "Sources feed Memory; Memory holds durable product records."
+problem: "Without a clear boundary, pipelines and storage blur."
+why: "Separating ingest from durable memory keeps provenance and retries understandable."
+mentalModel: "Source → validated content → Memory record."
+audiences: ["developers", "builders"]
+related: ["raw-records"]
+---
+# Sources and Memory
+
+Sources feed Memory; Memory holds durable product records.
+
+## Problem
+
+Without a clear boundary, pipelines and storage blur.
+
+## Why
+
+Separating ingest from durable memory keeps provenance and retries understandable.
+
+## Mental model
+
+Source → validated content → Memory record.

package/files/concepts/traversal.md

@@ -0,0 +1,27 @@
+---
+id: "traversal"
+type: "concept"
+title: "Forward and inverse traversal"
+summary: "Traversal follows definitions forward or inverse, optionally expanding targets."
+problem: "Callers guess direction and miss inverse edges."
+why: "Explicit direction matches authored relationship semantics."
+mentalModel: "Pick definition → direction → expand or not."
+audiences: ["developers"]
+prerequisites: ["relationship-references"]
+related: ["resolved-unresolved"]
+---
+# Forward and inverse traversal
+
+Traversal follows definitions forward or inverse, optionally expanding targets.
+
+## Problem
+
+Callers guess direction and miss inverse edges.
+
+## Why
+
+Explicit direction matches authored relationship semantics.
+
+## Mental model
+
+Pick definition → direction → expand or not.

package/files/diagrams/agent-inheritance.md

@@ -0,0 +1,34 @@
+---
+id: "agent-inheritance"
+type: "diagram"
+title: "Agent inheritance"
+summary: "Parent and child agents resolve into effective definitions."
+why: "Explains why Studio shows effective results, not only local files."
+diagramType: "hierarchy"
+---
+# Agent inheritance
+
+Parent and child agents resolve into effective definitions.
+
+## Why
+
+Explains why Studio shows effective results, not only local files.
+
+## How to read
+
+Parents contribute first; children may replace or add.
+
+## Text alternative
+
+Parent agent definitions flow to a child agent; the effective model is what runtime uses after resolution.
+
+## Nodes
+
+- **Parent agent** (`parent`)
+- **Child agent** (`child`)
+- **Effective definitions** (`effective`)
+
+## Edges
+
+- parent → child (inherit)
+- child → effective (resolve)

package/files/diagrams/intelligence-journey.md

@@ -0,0 +1,38 @@
+---
+id: "intelligence-journey"
+type: "diagram"
+title: "Intelligence journey"
+summary: "Evidence can yield analysis, decision, and proposals that still require explicit install."
+why: "Keeps human confirmation on runtime-changing actions."
+diagramType: "flow"
+---
+# Intelligence journey
+
+Evidence can yield analysis, decision, and proposals that still require explicit install.
+
+## Why
+
+Keeps human confirmation on runtime-changing actions.
+
+## How to read
+
+Proposals do not skip the install confirmation gate.
+
+## Text alternative
+
+Source and content evidence can produce analysis and a decision. An intelligence proposal may follow but requires explicit human-controlled installation or operational action.
+
+## Nodes
+
+- **Evidence** (`evidence`)
+- **Analysis** (`analysis`)
+- **Decision** (`decision`)
+- **Proposal** (`proposal`)
+- **Explicit action** (`install`)
+
+## Edges
+
+- evidence → analysis
+- analysis → decision
+- decision → proposal
+- proposal → install (confirm)

package/files/diagrams/memorix-central-journey.md

@@ -0,0 +1,51 @@
+---
+id: "memorix-central-journey"
+type: "diagram"
+title: "Memorix central product journey"
+summary: "Conceptual path from scope through metadata, records, relationships, analysis, and decisions."
+why: "Orients every concept page in the same mental model."
+diagramType: "journey"
+audiences: ["developers", "builders"]
+---
+# Memorix central product journey
+
+Conceptual path from scope through metadata, records, relationships, analysis, and decisions.
+
+## Why
+
+Orients every concept page in the same mental model.
+
+## How to read
+
+Left to right is conceptual learning order — not an auto-discovered runtime trace.
+
+## Text alternative
+
+Scope leads to explicit metadata and an effective model, then to concrete/raw data, composition and abstracts, relationships, analysis, and decisions/operation.
+
+## Nodes
+
+- **Scope** (`scope`)
+- **Explicit metadata** (`metadata`)
+- **Effective model** (`effective`)
+- **Raw/concrete** (`raw`)
+- **Composition/abstracts** (`compose`)
+- **Relationships** (`rels`)
+- **Analysis** (`analysis`)
+- **Decisions** (`decisions`)
+
+## Edges
+
+- scope → metadata (select)
+- metadata → effective (install/resolve)
+- effective → raw (shape data)
+- raw → compose (project)
+- compose → rels (link)
+- rels → analysis (evaluate)
+- analysis → decisions (commit)
+
+## Key takeaways
+
+- Conceptual journey
+- Each stage links to concepts
+- Not a discovered trace