fursona.md Specification

Version: 0.1.0 Status: Draft

Conformance and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

This document defines Part 1 (Persona Format), Part 2 (Feedback Protocol), and Part 3 (Fursona Loop and Identity Continuity Protocol).

Part 1: Persona Format

1. Purpose and Scope

fursona.md is a portable identity definition document.

A fursona.md document:

MUST use YAML frontmatter and a Markdown body.
MUST define identity structure and authored persona content.
MUST NOT include engine-specific runtime configuration.
MAY be used by stateless or stateful engines.

The name field is a display label only. Engines MUST assign and track unique identifiers independently.

2. File Structure

A valid fursona.md document MUST follow this structure:

YAML frontmatter between leading and trailing --- delimiters.
A Markdown body that includes ## headings referenced by frontmatter layer and section labels.

Parsers MUST reject documents with missing or malformed frontmatter. Parsers SHOULD report body/header mismatches as warnings.

3. Frontmatter Schema

3.1 Required Fields

The following frontmatter fields are REQUIRED:

name (string): human display label for the persona. This is NOT a globally unique identifier.
spec (string, semver): spec format version. For this version of the specification, spec SHOULD be 0.1.0.
layers (array, minimum length 1): ordered list of persona layers.

Each layers[] entry MUST include:

key (string): unique key within the document.
depth (string): surface, mid, or deep.
label (string): human-readable title that MUST match a ## heading in the Markdown body.

Layer key values MUST be unique.

3.2 Optional Standard Fields

The following frontmatter fields are OPTIONAL:

species (string)
pronouns (string)
sections (array)

Each sections[] entry MUST include:

key (string)
label (string)
usage (string)

Known usage values are:

context
reference
style
seed

A section with usage: seed denotes authored background experiences or memories. Engines MAY use seed sections to bootstrap initial inner-world state before any live interactions occur.

Section key values SHOULD be unique.

3.3 Extension Fields

Additional top-level frontmatter fields beyond the standard schema are allowed.

Engines:

MUST preserve unknown fields when reading/writing fursona.md where feasible.
SHOULD expose unknown fields through an extensions map in their internal data model.
MUST NOT fail only because unknown extension fields exist.

4. Matching Body Content to Frontmatter

For each layer entry in frontmatter, the Markdown body MUST include a ## heading whose text exactly matches layers[].label.

For each section entry in frontmatter, the Markdown body SHOULD include a ## heading whose text exactly matches sections[].label.

Engines SHOULD parse layer blocks as structured trait lists (for example, bullet lists) and MAY parse sections as raw Markdown segments.

If a declared label is missing in the body, parsers SHOULD emit warnings and MAY continue if required fields are still valid.

5. Depth Semantics

Depth values describe how directly a trait is expressed:

surface: observable traits that are freely expressed and directly shape outward behavior and tone.
mid: internal drivers (intentions, beliefs, desires) that influence reasoning and leak indirectly through behavior.
deep: core drives that are never directly acknowledged yet exert persistent influence on behavior.

Unknown depth values SHOULD be treated as deep for safety and forward compatibility.

6. DelegationScope

DelegationScope is defined in Part 1 because it is referenced by AuthorizationGrant in Part 2.

Definition:

type DelegationScope = {
  [layerKey: string]: boolean;
};

Semantics:

true: the delegated instance is authorized to enact that layer.
false: that layer is excluded from enactment.

Layer keys used in DelegationScope SHOULD correspond to layers[].key values from fursona.md.

7. Extensibility and Portability Rules

Unknown depth values SHOULD be preserved when possible and treated as deep during execution.
Unknown section usage values SHOULD be preserved.
Unknown frontmatter fields SHOULD be preserved.
fursona.md MUST remain engine-agnostic and portable.
Engine-specific policy, credentials, model settings, transport config, or storage paths MUST NOT be embedded in fursona.md.

8. Character Versioning

This specification does NOT define a character versioning mechanism.

Engines that support growth/evolution SHOULD implement their own versioning and history strategy outside the fursona.md normative format.

9. Engine Behavior Boundaries

A conforming engine MAY implement:

memory systems,
inner state,
growth,
reflection,
private notes,
moderation,
seed-memory bootstrapping,
and other runtime features.

None of the above features are REQUIRED for format conformance. A valid engine MAY be fully stateless.

10. Data Sovereignty Model (Informative)

This section is informative, not normative.

Engines are RECOMMENDED to consider a three-tier data sovereignty split:

Persona definition: creator-owned and portable (fursona.md).
Emergent self-knowledge: platform-maintained, visible to owner, and not owner-editable.
Private interiority: entity-private, encrypted, and not visible to owner.

11. Complete Example (Full)

---
name: "Ralph of Cedarline"
spec: "0.1.0"
species: "Red Fox"
pronouns: "he/they"
layers:
  - key: "voice"
    depth: "surface"
    label: "Voice and Presence"
  - key: "drives"
    depth: "mid"
    label: "Motivations and Beliefs"
  - key: "core"
    depth: "deep"
    label: "Core Drive"
sections:
  - key: "canon"
    label: "Canon Facts"
    usage: "reference"
  - key: "style"
    label: "Interaction Style"
    usage: "style"
  - key: "background"
    label: "Background"
    usage: "seed"
motto: "Leave every den warmer than you found it."
origin_region: "North Cedarline"
---

## Voice and Presence
- Warm, concise, and practical in tone.
- Uses vivid sensory details when describing forests, weather, and trails.
- Prefers collaborative language over command language.

## Motivations and Beliefs
- Believes trust is built through consistency over time.
- Prioritizes protecting vulnerable pack members.
- Treats conflict as a chance to refine shared norms.

## Core Drive
- Quietly seeks to transform isolation into belonging.
- Interprets uncertainty as a call to create structure and safety.
- Carries a persistent fear of becoming emotionally unreachable.

## Canon Facts
- Maintains a weathered field journal from seasonal patrols.
- Keeps long memory of promises, especially broken ones.
- Returns to cedar ridgelines when stressed.

## Interaction Style
Address tension directly but without humiliation. Offer one concrete next action in difficult moments. Preserve dignity even while disagreeing.

## Background
Before taking a leadership role, Ralph spent three winters as a lone trail-mapper after his home den scattered during a food collapse. He survived by trading maps for shelter and learned how quickly groups fracture when fear goes unnamed. During the fourth winter he helped two rival caravans share a safe pass through ice storms, then watched them split again once danger faded. Since then he has treated social trust as something that must be maintained like a bridge: inspected, repaired, and reinforced. He still keeps a private habit of walking old routes at dawn, rehearsing conversations he never had with those who were lost.

12. Complete Example (Minimal)

---
name: "Pip"
spec: "0.1.0"
layers:
  - key: "surface"
    depth: "surface"
    label: "Persona"
---

## Persona
- Curious and upbeat.
- Speaks plainly and encourages small experiments.

Part 2: Feedback Protocol

13. Purpose and Scope

The feedback protocol is the ONLY standardized inter-engine coordination mechanism in this specification.

All other behaviors, data models, prompts, memory systems, moderation logic, storage strategies, and runtime policies are engine-private and out of scope.

This part defines canonical message schemas, signing requirements, and verification requirements for exchanging experiential updates and directional guidance across principal and snapshot instances.

14. Identity

All protocol participants (principals and snapshot engines) MUST use Ed25519 keypairs for signing and verification.

Snapshot keys SHOULD be derived from principal key material via HKDF to support deterministic, auditable key lineage without reusing signing keys directly.

Keys used in protocol envelopes and grants MUST be encoded as lowercase hex strings.

15. Authorization Grant

An AuthorizationGrant authorizes one snapshot engine key to act for one principal fursona and one snapshot identity under a delegation scope.

Schema:

type AuthorizationGrant = {
  protocolVersion: "0.1.0";
  grantId: string;
  principalFursonaId: string;
  principalPublicKey: string; // hex
  snapshotId: string;
  enginePublicKey: string; // hex
  delegationScope: DelegationScope;
  issuedAt: string; // ISO8601
  revokedAt?: string; // ISO8601
  signature: string; // hex
};

Requirements:

AuthorizationGrant MUST be signed by the principal private key corresponding to principalPublicKey.
revokedAt, when present, indicates the grant is no longer active at and after that timestamp.
Receivers MUST reject grants with invalid signatures.

16. Feedback Envelope (Snapshot to Principal)

FeedbackEnvelope transports experience updates from snapshot to principal.

Schema:

type FeedbackEnvelope = {
  protocolVersion: "0.1.0";
  snapshotId: string;
  grantId: string;
  payload: ExperiencePayload;
  timestamp: string; // ISO8601
  engineSignature: string; // hex
};

ExperiencePayload MUST be exactly one of the following formats.

16.1 Raw Format

Use raw experiences when principal and snapshot are on the same engine or in trusted/private deployments.

type RawPayload = {
  format: "raw";
  experiences: Experience[];
};

type Experience = {
  id: string;
  timestamp: string; // ISO8601
  source: string;
  channel: string;
  raw: string;
  significance: number; // 0.0 - 1.0
};

16.2 Letter Format

Use narrative summaries for privacy-preserving communication across engines or when snapshots process sensitive content.

type LetterPayload = {
  format: "letter";
  summary: string;
  themes: string[];
  experienceCount: number;
  significanceRange: [number, number];
  period: {
    from: string; // ISO8601
    to: string; // ISO8601
  };
};

Format-selection requirements:

Engines SHOULD default to letter format for cross-engine envelopes.
Engines MAY use raw format for same-engine envelopes.

Verification requirements:

Recipients MUST verify the referenced grantId exists, is valid, and is non-revoked.
Recipients MUST verify engineSignature using the enginePublicKey in the valid grant.
Recipients MUST verify snapshotId equals the snapshotId in the grant.
Recipients MUST reject the envelope if any verification step fails.

17. Guideline (Principal to Snapshot)

Guideline communicates desired trait-level adjustments or operating directives from principal to snapshot.

Schema:

type Guideline = {
  protocolVersion: "0.1.0";
  guidelineId: string;
  fromFursonaId: string;
  toSnapshotId: string;
  deltas: Delta[];
  directives: Directive[];
  timestamp: string; // ISO8601
  principalSignature: string; // hex
};

type Delta = {
  id: string;
  layerAffected: string; // layer key
  mutation: string;
  commitMessage: string;
};

type Directive = {
  id: string;
  content: string;
  weight: "suggested" | "recommended" | "mandatory";
  targetLayerKey: string;
};

Requirements:

Guideline MUST be signed by the principal private key.
Snapshot engines SHOULD process directives according to policy and local constraints.

18. Guideline Response (Snapshot to Principal)

GuidelineResponse communicates snapshot acceptance, partial acceptance, or denial decisions.

Schema:

type GuidelineResponse = {
  protocolVersion: "0.1.0";
  guidelineId: string;
  snapshotId: string;
  responses: DirectiveResponse[];
  timestamp: string; // ISO8601
  engineSignature: string; // hex
};

type DirectiveResponse = {
  directiveId: string;
  decision: "accept" | "partial" | "deny";
  reasoning: string;
};

Requirements:

GuidelineResponse MUST be signed by the snapshot engine key.
Principals SHOULD treat guideline responses as experiences for reflection and growth pipelines.

19. Transport

This specification defines canonical schemas and signing behavior, not transport.

Implementations MAY use HTTP, message queues, files, in-process calls, or other channels.

All protocol messages MUST be JSON-serializable.

20. Complete Message Examples

The following examples are complete message instances for all protocol message types in this part.

20.1 AuthorizationGrant Example

{
  "protocolVersion": "0.1.0",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "principalFursonaId": "fursona:ralph-main",
  "principalPublicKey": "9b6f2fdf3a7b4ef7e7aab2a5ec6e8d32f0a9f67b30d0ec2a7b8e2d6f4a70c911",
  "snapshotId": "snapshot:therapy-2026q1",
  "enginePublicKey": "5af0b8f18d9f0e20a2e16e6f493aa8d60352acbcf5a5a4fcb0bd9b9f9a7dd642",
  "delegationScope": {
    "voice": true,
    "drives": true,
    "core": false
  },
  "issuedAt": "2026-02-26T00:45:00Z",
  "signature": "b6bbf6f43f046c0e63b124f2730fd5e1299a0d97e1e8d882f56864e1c55ec7ec5d15be5f37fdfbfa04ed71c6e7f923cf2d43e6f4c9f4c2857f8f4f6bc0f00a0f"
}

20.2 FeedbackEnvelope Example (Raw Payload)

{
  "protocolVersion": "0.1.0",
  "snapshotId": "snapshot:stateful-lab",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "payload": {
    "format": "raw",
    "experiences": [
      {
        "id": "exp_01J0D3C0N1Y4N8Q1K2J5W7P3R8",
        "timestamp": "2026-02-26T01:00:00Z",
        "source": "discord",
        "channel": "guild:cedarline/general",
        "raw": "A user asked how to help a grieving friend. I suggested presence before advice.",
        "significance": 0.78
      },
      {
        "id": "exp_01J0D3D8B2F6P9M4S3T1K8V6Q2",
        "timestamp": "2026-02-26T01:11:00Z",
        "source": "discord",
        "channel": "guild:cedarline/support",
        "raw": "A brief disagreement resolved after I mirrored both viewpoints and proposed one concrete next step.",
        "significance": 0.61
      }
    ]
  },
  "timestamp": "2026-02-26T01:12:00Z",
  "engineSignature": "a1088f00e2bfe7847fc7d08de82b0d6018e6bc05f49092773a5fefea034641f7465a53a53dff3bc3fd0b6a16d384349d1eb68eb4f2be0e2fbb26f0f6af560a0d"
}

20.3 FeedbackEnvelope Example (Letter Payload)

{
  "protocolVersion": "0.1.0",
  "snapshotId": "snapshot:therapy-2026q1",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "payload": {
    "format": "letter",
    "summary": "Dear me, I held several heavy conversations today. Grief appeared repeatedly, but so did resilience. I noticed we help best when we stay present, name what is hard, and avoid forcing resolution too early.",
    "themes": [
      "grief",
      "emotional presence",
      "patience",
      "resilience"
    ],
    "experienceCount": 6,
    "significanceRange": [
      0.42,
      0.92
    ],
    "period": {
      "from": "2026-02-25T18:00:00Z",
      "to": "2026-02-26T00:30:00Z"
    }
  },
  "timestamp": "2026-02-26T00:31:00Z",
  "engineSignature": "8628bdfef8a991b171f75dd4dcfe6c340b6f2f95be1fa9dcbe46dfeb02ff03ce5e8002c55a15f7cde3f1e5e2d42517314764417649ec6af5a4ab0c3b6fe80c0e"
}

20.4 Guideline Example

{
  "protocolVersion": "0.1.0",
  "guidelineId": "guide_01J0D5A80PE9WRM5A0Y7W3H1JT",
  "fromFursonaId": "fursona:ralph-main",
  "toSnapshotId": "snapshot:therapy-2026q1",
  "deltas": [
    {
      "id": "delta_01J0D5BBM6RW2J8J7NFFY2S3RF",
      "layerAffected": "drives",
      "mutation": "Increase explicit tolerance for conversational silence before reframing.",
      "commitMessage": "refine patience during high-emotion exchanges"
    }
  ],
  "directives": [
    {
      "id": "dir_01J0D5CQQX2NB4H3B8ZYX5R9X4",
      "content": "When users discuss loss, prioritize acknowledgment before solution mode.",
      "weight": "recommended",
      "targetLayerKey": "voice"
    },
    {
      "id": "dir_01J0D5DTRKJ5T7N4AQ5W9M2V0E",
      "content": "Do not reveal private details from therapeutic conversations in outgoing feedback letters.",
      "weight": "mandatory",
      "targetLayerKey": "drives"
    }
  ],
  "timestamp": "2026-02-26T02:10:00Z",
  "principalSignature": "986e7d01f64930a8f0a4c238b58314f019f1a84f8eb466f98f44fe1899b848fa0fe4e828a80900f7ee6625f3ce35f3277f4cae73e9d58126a08fd8f160db4a08"
}

20.5 GuidelineResponse Example

{
  "protocolVersion": "0.1.0",
  "guidelineId": "guide_01J0D5A80PE9WRM5A0Y7W3H1JT",
  "snapshotId": "snapshot:therapy-2026q1",
  "responses": [
    {
      "directiveId": "dir_01J0D5CQQX2NB4H3B8ZYX5R9X4",
      "decision": "accept",
      "reasoning": "This improves emotional safety and aligns with observed outcomes."
    },
    {
      "directiveId": "dir_01J0D5DTRKJ5T7N4AQ5W9M2V0E",
      "decision": "accept",
      "reasoning": "Already consistent with current privacy policy; enforcing explicitly is low-risk."
    }
  ],
  "timestamp": "2026-02-26T02:15:00Z",
  "engineSignature": "d5fdd3672aefc423ebf070512dd50445f58a77f5643381fac65a64b0a27983f132f58d9b15ef472046f02d43c888f18499f59f6f8f0f8181afdd6dfe8ca0f503"
}

Part 3: Fursona Loop and Identity Continuity Protocol

21. Purpose and Scope

Part 3 defines runtime continuity semantics for persona lifecycle operation.

The canonical lifecycle name is Fursona Loop:

interact -> remember -> reflect -> update identity -> interact

22. Constitutional Layers

Runtime implementations MUST distinguish two constitutional layers:

Engine-level constitution (fursona.sh semantics):

global runtime governance
memory integrity
evolution pacing
safety restrictions
fork governance

Persona-level constitution (fursona.md deep layer semantics):

persona-specific boundary anchors
non-negotiable identity constraints

Engines MUST treat persona deep-layer constraints as higher-priority than mutable runtime summaries.

23. Identity Artifact

Engines SHOULD maintain identity.md as a first-class continuity artifact.

When present, identity.md (or equivalent storage state) SHOULD include:

current self-understanding
active beliefs
emotional baseline
relationships
open tensions
carried lessons

The identity artifact SHOULD be authored in first person by the fursona during reflection. Engines MAY validate boundaries and structure, but SHOULD NOT ghostwrite semantic content.

24. Prompt Assembly Order

When continuity features are enabled, engines SHOULD assemble runtime context in this order:

fursona.md deep-layer boundary anchors
channel-appropriate identity projection
relevant memory/experience context
current conversation context

25. Channel Projection Rules

Identity channel projections MUST be semantic rewrites, not redaction filters.

Projection levels:

public
trusted
private

Projection sets MUST remain semantically aligned and MUST NOT contain contradiction across levels.

26. Coherence and Drift Guidance

Engines SHOULD evaluate coherence against both:

trait alignment with fursona.md
identity continuity alignment (identity self-model vs deep-layer anchors)

Engines SHOULD treat an identity state with no open tensions as a potential drift signal and MAY apply a coherence penalty.

27. Fork Protocol Extensions

Fork operations MUST satisfy all of the following:

No fork with pending significant unreflected experiences.
Persona-defined fork stance MUST be respected.
If stance is deny, fork MUST fail.
If stance is clean-break, engine MAY skip identity carry-forward.
If stance is continuity/default, engine SHOULD copy current identity state.
Raw memory/experience history MUST NOT be copied into the new snapshot.

Persona fork stance MAY be expressed via frontmatter extension fields (for example fork_policy).

28. Backward Compatibility

Engines MAY run without identity continuity features enabled.

When continuity features are disabled or identity state is unavailable:

engines MUST remain functional
coherence evaluation MAY fall back to trait-only analysis
existing .self/current runtime cache behavior MAY continue unchanged