The Ontology & Portable Memory

Status: 🔭 designed. This page describes the memory layer Pinard is building toward (the memory-layer change). The shipped memory system is Memory & Recall.

For a fleet’s knowledge to be queryable and portable, it has to be typed. Pinard types memory with a layered ontology and ships it as versioned, portable subsets.

A sketched grapevine with a stable shared trunk, distinct domain branches, young learned shoots, one human-reviewed graft toward the core, and a three-compartment portable case holding runtime, process, and memory. L1 · pinard-core L2 · repository ontology Learned types Human-reviewed promotion Portable agent · one versioned unit
Stable core, specialized branches, deliberate promotion. Repository ontologies extend the shared operational vocabulary; learned types remain local unless recurrence and human review justify promotion.
  • L1pinard-core — the small, stable operational trunk shared by every agent.
  • L2Repository ontology — domain concepts branch from and subclass the core.
  • ↑Learned → promoted — only a reviewed, proven domain type is grafted toward core.
  • ▣Portable agent — runtime, process.js, and scoped memory are versioned together.

Why layered

A single flat ontology forces a false choice: either it is generic and useless, or it bakes one domain’s specifics (say, GWAS/HPC terms) into what should be shared by everyone. Pinard splits it into two layers instead.

Layer 1 — pinard-core

Repo-agnostic, agent-operational concepts that mirror the primitives of a semi-deterministic loop. Small and stable, versioned centrally in Pinard:

  • Entities: Task / Step, Verdict / Decision, Gate (a breakpoint), Action, Diagnosis, LogPattern, EnvironmentCondition, Artifact.
  • Edges: DependsOn, Produces, Consumes, IndicatesProblem, ResolvedBy, RequiresCondition, TriggersDecision.

Layer 2 — per-repo domain

Each repository defines its own ontology that subclasses core and lives next to its process.js. For example, a GWAS pipeline repo might define:

  • SlurmJob is-a Task/execution
  • ShardThresholdDecision is-a Decision
  • GWASStudy is-a Artifact
  • ProvenanceRecord

Granularity is per-repo by default (a per-process override only where a process genuinely diverges; per-agent is too granular). A data-pipeline mid-layer between core and domain is deferred but intended.

Lifecycle: prescribed → learned → promoted

Types are not frozen. They move through a lifecycle:

  • prescribed — declared up front (core, or a repo’s domain);
  • learned — new types emerge during /teaching sessions;
  • promoted — a proven domain type is elevated toward core.

Promotion domain → core is human-gated (a git PR), and a suppressed_types list retires types that stop earning their place. This is the same recurrence-plus-review pattern used for rule and scope promotion.

Portable memory subsets

This is the payoff of a single, embeddable store of record. The central memory (SurrealDB server) can be subset — scoped to a repo or pipeline — into a specialized embedded SurrealDB file that an agent loads locally.

That makes a pinard agent a self-contained, reproducible artifact:

 pinard agent  =  harness  +  babysitter process  +  memory subset
                  (the runtime) (the loop, process.js) (embedded, scoped store)

All three are versioned together (e.g. in ExoHub), so an agent-centric data pipeline is reproducible and auditable: you can rebuild exactly the agent, its loop, and the knowledge it had at a given version.

Version-stamping

Every portable subset version-stamps both the pinard-core ontology version and the domain ontology version it was extracted under. A migration policy governs what happens when core or domain versions change under an already-shipped subset — new, load-bearing scope that portability introduces.

Next