Architecture

Architecture

Zeref OS comprises four main layers:

1. AGENTS.md (Source of Truth): Central spec that lists all agents, skills, commands, team packs, and global rules. All harness-specific files (e.g. CLAUDE.md, CURSOR.md) are thin stubs that refer back to this spec.

2. Agents (Always-on): Six background roles that run every session:

   • memory-keeper – Single writer to the flat memory/; handles all reads/writes/logs.
   • privacy-guardian – Enforces PRIVACY.md, REDACT.md, and SHARING_POLICY.md on every operation.
   • sync-coordinator – Manages file permissions and parent-sync when using /sync-parent.
   • evidence-curator – Attaches confidence and provenance tags to memory entries.
   • pattern-observer – Watches memory/patterns/PATTERNS.jsonl for repeats (triggers skill drafts).
   • handoff-orchestrator – On /stop, packages the session for cross-harness handoff.

3. Skills (On-trigger): Ten specialized skills in skills/ (e.g. pattern-to-skill, budget-governor, wiki-maintenance) that execute when their trigger phrases are detected in prompts.

4. Commands: Eight user commands documented in commands/ (such as /start, /stop, /team, /review-skill, etc.) that the user invokes to control Zeref OS.

5. Team Packs (On-demand): Pre-defined multi-agent workflows (solo, build, research, red, audit, ship). For instance, /team audit runs a security audit team with 3 agents, and outputs all findings in team/audit/.

flowchart LR
  User((User)) -->|`/zeref-os:command`| Harness
  Harness -->|reads| AG[AGENTS.md]
  AG --> Agents
  AG --> Skills
  AG --> Commands
  AG --> TeamPacks

  subgraph Agents["6 agents — always-on"]
    MK[memory-keeper]
    PG[privacy-guardian]
    SC[sync-coordinator]
    EC[evidence-curator]
    PO[pattern-observer]
    HO[handoff-orchestrator]
  end

  subgraph Skills["10 skills — on-trigger"]
    PS[project-setup]
    WM[wiki-maintenance]
    CR[contradiction-resolution]
    PA[privacy-abstraction]
    PSY[parent-sync]
    P2S[pattern-to-skill]
    MIE[memory-import-export]
    BG[budget-governor]
    HC[handoff-compiler]
    EG[evidence-grader]
  end

  subgraph Commands["8 commands"]
    C1[start]
    C2[stop]
    C3[status]
    C4[reset-permissions]
    C5[sync-parent]
    C6[review-skill]
    C7[team]
    C8[done]
  end

  subgraph TeamPacks["6 team packs — on-demand"]
    TP1[solo]
    TP2[build]
    TP3[research]
    TP4[red: read-only]
    TP5[audit]
    TP6[ship]
  end

  MK <--> Mem[(memory/ flat)]
  PG -. "enforces policies" .-> Mem
  PO -. "logs patterns" .-> PJ["memory/patterns/PATTERNS.jsonl"]

## Core Flows:
On startup or /start, Zeref loads AGENTS.md, then the user’s memory/hot.md and memory/index.md as context.
On every write, memory-keeper updates the flat file log (ensuring no two processes write simultaneously).
When a skill is triggered, it may read/write memory or propose new files (e.g. pattern-to-skill creates skills/drafts/).
Team packs spin up multiple agents working together; outputs always go into team/<pack>/.
csharp
Copy

## Memory System

```markdown
# Memory System

Zeref’s memory is a **flat Markdown wiki** stored under the `memory/` directory in the project.

memory/ ├── hot.md # <500 words — the last 3 sessions (read first) ├── index.md # Main domain index (read if hot.md insufficient) ├── DECISIONS.md # Important resolved questions (append-only) ├── OPEN_QUESTIONS.md # Unresolved questions needing answers ├── RISKS.md # Potential issues identified (high/med/low) ├── CONFLICTS.md # Contradictions flagged by the system ├── MEMORY.md # Freeform notes and context ├── patterns/ │ └── PATTERNS.jsonl # Append-only log of repeated tasks detected └── archive/ └── ... # Archived snapshots and older logs

pgsql
Copy

- **Read Order (per AGENTS.md):** Agents read `hot.md` first (immediate context), then `index.md`. Individual domain pages are loaded only as needed.
- **Append-only:** All entries in `memory/` are appended. Edits to `index.md` or `DECISIONS.md` always preserve history. `PATTERNS.jsonl` never overwrites old patterns.
- **Session Hot Log:** Each session’s output (up to 500 words) is appended to `hot.md`. When `hot.md` is “full”, older text is moved into archived logs.
- **Parent Sync (Optional):** When merging to a parent project, approved changes from these files are pushed as a new commit in the parent repository, preserving the author and timestamp.

Loading