Ecosystem Shared Artifact Schema

Status: Phase 2 baseline implemented Owner: learning_ai_common_plat Purpose: Define the canonical cross-product artifact model so notes, transcripts, plans, memories, trails, routes, and agent outputs can interoperate cleanly.

1. Problem

Multiple repos produce durable user-value objects:

LysnrAI transcripts
NoteLett notes
MindLyst memory entries
FlowMonk plans
ChronoMind routines
ActionTrail audit records
PeakPulse sessions
Cowork generated reports and file outputs

Today these are product-local objects. The ecosystem needs one canonical artifact shape so:

artifacts can be linked, searched, and retrieved consistently
provenance can be preserved
agent outputs can become user-editable assets
one user action can create downstream value across products

2. Goals

Define one envelope schema shared across all products.
Preserve product-specific payloads inside a canonical wrapper.
Support provenance, lineage, and visibility rules.
Support human-created, machine-created, and mixed artifacts.
Support cloud-first and local-first storage models.

3. Non-Goals

Replacing product-local domain schemas entirely.
Forcing one storage backend for all products.
Removing product-specific UX or metadata.

4. Proposed Canonical Shape

Every artifact should include:

id
artifactType
productId
sourceSurface
title
summary
createdAt
updatedAt
createdBy
ownership
visibility
status
tags
links
provenance
payload

Example types:

transcript
note
memory
plan
routine
habit-checkin
trail-report
route-session
agent-output
document
digest

5. Minimum Envelope Fields

type ArtifactEnvelope = {
  id: string;
  artifactType: string;
  productId: string;
  sourceSurface: string;
  title: string | null;
  summary: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    actorType: 'user' | 'agent' | 'system' | 'mixed';
    actorId: string | null;
  };
  ownership: {
    userId: string;
    orgId?: string | null;
  };
  visibility: {
    scope: 'private' | 'org' | 'shared' | 'local-only';
    allowedProducts?: string[];
  };
  status: string;
  tags: string[];
  links: ArtifactLink[];
  provenance: ArtifactProvenance;
  payload: Record<string, unknown>;
};

type ArtifactLink = {
  relation:
    | 'derived-from'
    | 'summarizes'
    | 'generated-task'
    | 'generated-routine'
    | 'generated-memory'
    | 'evidence-for'
    | 'review-of'
    | 'attached-to';
  targetArtifactId: string;
};

type ArtifactProvenance = {
  originProductId: string;
  originActionId?: string | null;
  sessionId?: string | null;
  runId?: string | null;
  approvalId?: string | null;
  lineage: Array<{
    stepType: string;
    productId: string;
    actorType: 'user' | 'agent' | 'system';
    timestamp: string;
  }>;
};

6. First Adopters

Phase 1 adopters:

learning_voice_ai_agent
learning_ai_notes
learning_multimodal_memory_agents
learning_ai_flowmonk
learning_ai_trails
oss/learning_ai_claw-cowork

Phase 2 adopters:

learning_ai_clock
learning_ai_efforise

7. Key Open Decisions

Should artifact IDs be globally unique UUIDs or product-prefixed IDs?
Which fields belong in the envelope vs product payload?
Should payload be versioned per artifact type?
How should local-only artifacts from learning_ai_local_memory_gpt be represented without leaking sync assumptions?
How should binary/file artifacts be referenced: inline metadata vs blob indirection?

8. Acceptance Criteria

A LysnrAI transcript can be wrapped as an artifact without losing transcript-specific metadata.
A NoteLett note can link back to a transcript artifact.
A MindLyst memory can record provenance to source transcript/note artifacts.
A Cowork output can be stored as an agent-output artifact and later opened in NoteLett.
ActionTrail can render provenance from the envelope alone.

9. Implementation Checklist

finalize canonical envelope field names and required/optional splits
define first 8 artifact types in stable form
define link relation vocabulary
define provenance minimum payload
define storage/binary attachment rules
define migration strategy for first adopters
add examples for LysnrAI, NoteLett, and MindLyst
add contract-backed examples for FlowMonk, ChronoMind, and EffoRise
add examples for Cowork and ActionTrail

Current implementation location:

Commits:

eae3409 drafted the initial stub
76f1b47 added Phase 1 artifact schemas and canonical fixtures
5460662 added Phase 2 artifact schemas for plan, routine, and habit

5.0 KiB Raw Blame History