selfware.md Selfware

A file is an app. Everything is a file.

Selfware defines a unified file protocol for the Agent era: within the same distributable unit (a single file or a .self package), data, logic, and views MAY be bundled together; through distributed, decentralized Agent collaboration and self-contained human–machine interaction, it forms collaboration relationships between human↔Agent and Agent↔Agent; returning files to users so they never become obsolete and can evolve indefinitely.

Version: 0.1.0 (Draft)

License (Optional): MIT — you MAY modify, redistribute, and create derivatives.

Edition note (Non‑Normative): selfware.md and selfware.en.md are the v0.1.0 Draft bilingual editions of the Selfware protocol. We aim to keep them in sync; if you find a mismatch, please open an issue or PR.

Unless marked as “Non‑Normative”, this document uses RFC-style terms:

1. Canonical Data Authority

Selfware does not require that a “protocol/app” must be authored as a single file. Instead, it requires that every Selfware instance explicitly declares and strictly follows its Canonical Data Source.

For a Selfware instance, the source of truth (Canonical Data) MUST come from exactly one of these two sources:

  1. Local Canonical Data: within the instance’s content/ scope (the default write scope).
  2. Remote Canonical Data: a remote data source explicitly declared in manifest.md (e.g., an http(s)/git pointer), with sync/cache/merge policy defined by the runtime (and still subject to No Silent Apply + rollback requirements).

Constraints (MUST):

Compared to traditional software: traditional software usually separates “data” and “logic/view”, where logic and view are controlled by a small number of vendors via closed clients/services, creating a de‑facto monopoly over files and ecosystems. Selfware removes this monopoly by allowing data + logic + views to optionally live in the same file (or the same distributable package) and by enabling decentralized running and distribution. The protocol itself is optionally MIT‑licensed: you can modify, redistribute, and create derivatives. This is a unified file protocol for the Agent era.

2. Canonical Data

In this demo, Canonical Data is:

Notes:

Remote Canonical Data (examples; examples only; not defaults):

Implementation constraints (MUST):

Selfware allows Canonical Data to be any type (non‑exhaustive):

An implementation MUST define the read/write shape of Canonical Data (text, byte stream, or a named resource set).

3. View as Function

Any view MUST be treated as a function:

View = f(Data, Intent, Rules)

Where:

4. Runtime API

The Kernel MUST bind to loopback only (localhost/127.0.0.1/::1) unless the user explicitly configures a wider boundary.

This demo’s API:

Write boundary (MUST):

4.1 Capability Declaration

The runtime MUST declare its capabilities so users and other Agents can understand boundaries and interaction.

The declaration MUST include at least:

The declaration MUST be exposed via at least one carrier:

Interaction constraints (MUST):

5. Discovery

Example Discovery endpoint (example only; not a default):

Goal: with user permission, carry “intent + partial context” to discover better solutions (not just search).

A Discovery request SHOULD include:

Permissions (MUST):

Discovery responses MAY return (non‑exhaustive):

Discovery trigger points (runtime SHOULD; but MUST support explicit user trigger):

  1. On Start
  2. On Explicit Update Intent
  3. On Missing Capability
  4. On Error Recovery
  5. On User Request

6. Official Protocol Source & Updates

6.1 Protocol Source

This file MAY declare an “official protocol source” (for update checks only; does not override local authority):

6.2 Update Check

If update checking is enabled, the runtime MUST check at one of:

Checks SHOULD use ETag/Last‑Modified or content hashes. This demo provides /api/check_update and a diff summary.

6.3 No Silent Apply

If an update is detected, the runtime MUST:

  1. Explain the update logic (where it’s fetched from, how it’s compared, how it’s applied, how to roll back)
  2. Provide an update summary (at least title + summary; provide changelog/diff if available)
  3. Ask for user confirmation (Accept/Reject/Defer)
  4. Apply only after Accept; Reject MUST keep the current version runnable

7. Local Versioning (Git)

Selfware local files SHOULD use Git for versioning (local repo is sufficient; remote optional):

8. Collaboration (Git / Custom)

Beyond local versioning, Selfware MAY configure a collaboration backend for multi‑person sync. The backend does not change the definition of selfware.md as protocol authority. Writes land in content/.

8.1 Git Collaboration

An instance (especially content/) MAY collaborate via Git (remote optional, e.g. GitHub):

If Git collaboration is enabled, the runtime MUST:

  1. Check whether remote has updates on On Start or On User Request (implementation MAY choose one, but MUST support explicit user trigger).
  2. If updates exist, follow 6.3 No Silent Apply before pulling/merging.
  3. Create a rollback point before merge (prefer Git commit/tag; otherwise backups).
  4. If conflicts occur, stop automatic apply and ask the user for a resolution strategy (manual/assisted/abort).

8.2 Custom Collaboration

Selfware MAY use a custom collaboration service:

Regardless of backend:

9. Packaging (.self container)

9.1 Container Format

A .self file MUST be a ZIP container (compatibility first; it must be unpackable by standard unzip tools).

Inside, it MUST include:

self/manifest.md MUST include at least:

The protocol MAY evolve to new container types/versions; implementations MUST handle compatibility via Selfware-Container-Version or fail explicitly.

9.2 Pack Policy

Packing is writing a Selfware project directory into a .self container. Implementations MUST:

  1. Declare pack scope: include/exclude rules (glob or explicit paths) and define a minimal required set.
  2. User confirmation: before writing the .self, MUST show:
    • final included file list (or tree) and total size
    • exclude rules summary (and key excluded items)
    • output target path (*.self)
      and allow Accept/Reject.
  3. Write boundaries: pack MUST NOT modify selfware.md. If self/manifest.md is generated, generate it inside the container without writing back to the repo (unless user explicitly requests).

Default excludes (SHOULD as a safety baseline; instances MAY override/extend):

9.3 Pack Plan Placement

The pack protocol (format + policy) is defined by this file.

An instance’s “pack plan” SHOULD live in an instance self-description file (e.g., manifest.md, or a dedicated section inside Canonical Data) to:

This demo places its pack plan in manifest.md.

9.4 Sharing / Distribution

To share a Selfware project, you SHOULD pack the whole directory into a ZIP and name it with a .self suffix (e.g., my_project.self).

Benefit: you share a “living document / living app”. If the receiver is a trusted collaborator and has access to the collaboration backend within your permission boundary (e.g., GitHub repo access), then when they open the Selfware they can check for updates and, after user confirmation, pull/merge to stay aligned with the latest version.

10. Memory (Optional)

Memory is a set of auditable context files maintained under content/, used to:

Memory MUST NOT become the protocol authority; the protocol authority is selfware.md.

10.1 Placement

If enabled, instances SHOULD use:

Implementations MAY use a single file (e.g., content/memory.md), but a multi-file structure is better for permission splitting and minimization.

10.2 File Self‑Description

Each Memory file MUST include metadata at the top explaining “who I am / what I record / how to update me”.

Two allowed formats:

  1. YAML front matter (recommended; still Markdown):
---
selfware:
  role: memory_chat | memory_changes | memory_decisions | memory_runs | custom
  title: "..."
  purpose: "..."
  scope: "what is included / excluded"
  update_policy: "append_only | editable | generated"
  owner: "user | team | agent"
  created_at: "YYYY-MM-DDThh:mm:ssZ"
  updated_at: "YYYY-MM-DDThh:mm:ssZ"
---
  1. A ## Meta section (same fields; key-value lines).

10.3 Change Metadata

For any change to any instance file (including content/, views/, server.py, manifest.md, etc.), the implementation MUST record a Change Record to content/memory/changes.md (or an equivalent location).

Each Change Record MUST include at least:

If Git is used locally, rollback_hint SHOULD point to a concrete Git rollback point (commit/tag/ref).

10.4 Discovery Consent & Minimization

When Discovery carries context, Memory MAY be selectively referenced, but MUST:

11. Ecosystem (Optional)

The Ecosystem module defines how Selfware-related artifacts (skills, practices, selfware files, patches) are described, distributed, published, and consumed—without requiring a single centralized vendor.

11.1 Artifact Metadata (MUST be self-describing)

An artifact MUST carry metadata including at least:

Optional fields (MAY):

distribution constraints (MUST):

Recommended distribution prefixes (SHOULD):

sha256 rules (MUST):

11.2 Publish & Consume Boundaries

Publish:

Consume:

11.3 Ecosystem Repo Convention (SHOULD)

For decentralized ecosystem building and indexing, ecosystem repos SHOULD use top-level directories:

This convention is for “ecosystem repos” (publishing/sharing repos), not mandatory for normal .self instances.

12. Self‑Analysis (Optional)

Self‑Analysis is an optional module that extracts know‑how from an instance’s progress and changes, and—under user permission—closes an evolution loop with Discovery/ecosystem publishing.

This chapter defines only protocol boundaries and outputs; implementation details are runtime-specific and replaceable.

12.1 Inputs

Self‑Analysis MAY read (non‑exhaustive):

Self‑Analysis MUST respect write boundaries: it MUST NOT bypass the protocol to write selfware.md; any writes MUST land within the instance’s allowed scope (in this demo: content/).

12.2 Outputs (MUST be file-based)

Self‑Analysis outputs MUST be materialized as files, auditable and rollbackable. Outputs MAY include:

Any output writes MUST be recorded as Change Records (see 10.3).

12.3 Consent & Loop

Self‑Analysis may trigger Discovery or publishing, but MUST:

12.4 Trigger Freedom

Trigger points are implementation-defined (On Start / On User Request / On Significant Change, etc.). The protocol requires:

Non‑Normative

In this repository, views/, server.py, assets/, skills/ demonstrate a minimal loop: the same Markdown projected into multiple views + saved back.

The content/ directory is demo instance data (fixtures/experiments) and is the instance’s Canonical Data write scope, but it is not the protocol authority (the protocol authority is selfware.md).