@fideliosai/server 2026.331.0-canary.0

package/skills/fidelios/references/company-skills.md

@@ -0,0 +1,193 @@
+# Company Skills Workflow
+
+Use this reference when a board user, CEO, or manager asks you to find a skill, install it into the company library, or assign it to an agent.
+
+## What Exists
+
+- Company skill library: install, inspect, update, and read imported skills for the whole company.
+- Agent skill assignment: add or remove company skills on an existing agent.
+- Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.
+
+The canonical model is:
+
+1. install the skill into the company
+2. assign the company skill to the agent
+3. optionally do step 2 during hire/create with `desiredSkills`
+
+## Permission Model
+
+- Company skill reads: any same-company actor
+- Company skill mutations: board, CEO, or an agent with the effective `agents:create` capability
+- Agent skill assignment: same permission model as updating that agent
+
+## Core Endpoints
+
+- `GET /api/companies/:companyId/skills`
+- `GET /api/companies/:companyId/skills/:skillId`
+- `POST /api/companies/:companyId/skills/import`
+- `POST /api/companies/:companyId/skills/scan-projects`
+- `POST /api/companies/:companyId/skills/:skillId/install-update`
+- `GET /api/agents/:agentId/skills`
+- `POST /api/agents/:agentId/skills/sync`
+- `POST /api/companies/:companyId/agent-hires`
+- `POST /api/companies/:companyId/agents`
+
+## Install A Skill Into The Company
+
+Import using a **skills.sh URL**, a key-style source string, a GitHub URL, or a local path.
+
+### Source types (in order of preference)
+
+| Source format | Example | When to use |
+|---|---|---|
+| **skills.sh URL** | `https://skills.sh/google-labs-code/stitch-skills/design-md` | When a user gives you a `skills.sh` link. This is the managed skill registry — **always prefer it when available**. |
+| **Key-style string** | `google-labs-code/stitch-skills/design-md` | Shorthand for the same skill — `org/repo/skill-name` format. Equivalent to the skills.sh URL. |
+| **GitHub URL** | `https://github.com/vercel-labs/agent-browser` | When the skill is in a GitHub repo but not on skills.sh. |
+| **Local path** | `/abs/path/to/skill-dir` | When the skill is on disk (dev/testing only). |
+
+**Critical:** If a user gives you a `https://skills.sh/...` URL, use that URL or its key-style equivalent (`org/repo/skill-name`) as the `source`. Do **not** convert it to a GitHub URL — skills.sh is the managed registry and the source of truth for versioning, discovery, and updates.
+
+### Example: skills.sh import (preferred)
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://skills.sh/google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+Or equivalently using the key-style string:
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+### Example: GitHub import
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://github.com/vercel-labs/agent-browser"
+  }'
+```
+
+You can also use source strings such as:
+
+- `google-labs-code/stitch-skills/design-md`
+- `vercel-labs/agent-browser/agent-browser`
+- `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
+
+If the task is to discover skills from the company project workspaces first:
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/scan-projects" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Inspect What Was Installed
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+Read the skill entry and its `SKILL.md`:
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/<skill-id>" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+
+curl -sS "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/skills/<skill-id>/files?path=SKILL.md" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+## Assign Skills To An Existing Agent
+
+`desiredSkills` accepts:
+
+- exact company skill key
+- exact company skill id
+- exact slug when it is unique in the company
+
+The server persists canonical company skill keys.
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/agents/<agent-id>/skills/sync" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "desiredSkills": [
+      "vercel-labs/agent-browser/agent-browser"
+    ]
+  }'
+```
+
+If you need the current state first:
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/agents/<agent-id>/skills" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+## Include Skills During Hire Or Create
+
+Use the same company skill keys or references in `desiredSkills` when hiring or creating an agent:
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/agent-hires" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+For direct create without approval:
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/agents" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+## Notes
+
+- Built-in FideliOS runtime skills are still added automatically when required by the adapter.
+- If a reference is missing or ambiguous, the API returns `422`.
+- Prefer linking back to the relevant issue, approval, and agent when you comment about skill changes.
+- Use company portability routes when you need whole-package import/export, not just a skill:
+  - `POST /api/companies/:companyId/imports/preview`
+  - `POST /api/companies/:companyId/imports/apply`
+  - `POST /api/companies/:companyId/exports/preview`
+  - `POST /api/companies/:companyId/exports`
+- Use skill-only import when the task is specifically to add a skill to the company library without importing the surrounding company/team/package structure.

package/skills/fidelios-create-agent/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: fidelios-create-agent
+description: >
+  Create new agents in FideliOS with governance-aware hiring. Use when you need
+  to inspect adapter configuration options, compare existing agent configs,
+  draft a new agent prompt/config, and submit a hire request.
+---
+
+# FideliOS Create Agent Skill
+
+Use this skill when you are asked to hire/create an agent.
+
+## Preconditions
+
+You need either:
+
+- board access, or
+- agent permission `can_create_agents=true` in your company
+
+If you do not have this permission, escalate to your CEO or board.
+
+## Workflow
+
+1. Confirm identity and company context.
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/agents/me" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+2. Discover available adapter configuration docs for this FideliOS instance.
+
+```sh
+curl -sS "$FIDELIOS_API_URL/llms/agent-configuration.txt" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+3. Read adapter-specific docs (example: `claude_local`).
+
+```sh
+curl -sS "$FIDELIOS_API_URL/llms/agent-configuration/claude_local.txt" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+4. Compare existing agent configurations in your company.
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/agent-configurations" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+5. Discover allowed agent icons and pick one that matches the role.
+
+```sh
+curl -sS "$FIDELIOS_API_URL/llms/agent-icons.txt" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+6. Draft the new hire config:
+- role/title/name
+- icon (required in practice; use one from `/llms/agent-icons.txt`)
+- reporting line (`reportsTo`)
+- adapter type
+- optional `desiredSkills` from the company skill library when this role needs installed skills on day one
+- adapter and runtime config aligned to this environment
+- capabilities
+- run prompt in adapter config (`promptTemplate` where applicable)
+- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
+
+7. Submit hire request.
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/companies/$FIDELIOS_COMPANY_ID/agent-hires" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "CTO",
+    "role": "cto",
+    "title": "Chief Technology Officer",
+    "icon": "crown",
+    "reportsTo": "<ceo-agent-id>",
+    "capabilities": "Owns technical roadmap, architecture, staffing, execution",
+    "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+    "adapterType": "codex_local",
+    "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+    "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
+    "sourceIssueId": "<issue-id>"
+  }'
+```
+
+8. Handle governance state:
+- if response has `approval`, hire is `pending_approval`
+- monitor and discuss on approval thread
+- when the board approves, you will be woken with `FIDELIOS_APPROVAL_ID`; read linked issues and close/comment follow-up
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/approvals/<approval-id>" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+
+curl -sS -X POST "$FIDELIOS_API_URL/api/approvals/<approval-id>/comments" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"body":"## CTO hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-ref>](/agents/<agent-url-key-or-id>)\n- Source issue: [<issue-ref>](/issues/<issue-identifier-or-id>)\n\nUpdated prompt and adapter config per board feedback."}'
+```
+
+If the approval already exists and needs manual linking to the issue:
+
+```sh
+curl -sS -X POST "$FIDELIOS_API_URL/api/issues/<issue-id>/approvals" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"approvalId":"<approval-id>"}'
+```
+
+After approval is granted, run this follow-up loop:
+
+```sh
+curl -sS "$FIDELIOS_API_URL/api/approvals/$FIDELIOS_APPROVAL_ID" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+
+curl -sS "$FIDELIOS_API_URL/api/approvals/$FIDELIOS_APPROVAL_ID/issues" \
+  -H "Authorization: Bearer $FIDELIOS_API_KEY"
+```
+
+For each linked issue, either:
+- close it if approval resolved the request, or
+- comment in markdown with links to the approval and next actions.
+
+## Quality Bar
+
+Before sending a hire request:
+
+- if the role needs skills, make sure they already exist in the company library or install them first using the FideliOS company-skills workflow
+- Reuse proven config patterns from related agents where possible.
+- Set a concrete `icon` from `/llms/agent-icons.txt` so the new hire is identifiable in org and task views.
+- Avoid secrets in plain text unless required by adapter behavior.
+- Ensure reporting line is correct and in-company.
+- Ensure prompt is role-specific and operationally scoped.
+- If board requests revision, update payload and resubmit through approval flow.
+
+For endpoint payload shapes and full examples, read:
+`skills/fidelios-create-agent/references/api-reference.md`

package/skills/fidelios-create-agent/references/api-reference.md

@@ -0,0 +1,105 @@
+# FideliOS Create Agent API Reference
+
+## Core Endpoints
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:adapterType.txt`
+- `GET /llms/agent-icons.txt`
+- `GET /api/companies/:companyId/agent-configurations`
+- `GET /api/companies/:companyId/skills`
+- `POST /api/companies/:companyId/skills/import`
+- `GET /api/agents/:agentId/configuration`
+- `POST /api/agents/:agentId/skills/sync`
+- `POST /api/companies/:companyId/agent-hires`
+- `POST /api/companies/:companyId/agents`
+- `GET /api/agents/:agentId/config-revisions`
+- `POST /api/agents/:agentId/config-revisions/:revisionId/rollback`
+- `POST /api/issues/:issueId/approvals`
+- `GET /api/approvals/:approvalId/issues`
+
+Approval collaboration:
+
+- `GET /api/approvals/:approvalId`
+- `POST /api/approvals/:approvalId/request-revision` (board)
+- `POST /api/approvals/:approvalId/resubmit`
+- `GET /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/comments`
+- `GET /api/approvals/:approvalId/issues`
+
+## `POST /api/companies/:companyId/agent-hires`
+
+Request body matches agent create shape:
+
+```json
+{
+  "name": "CTO",
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "uuid-or-null",
+  "capabilities": "Owns architecture and engineering execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "adapterType": "claude_local",
+  "adapterConfig": {
+    "cwd": "/absolute/path",
+    "model": "claude-sonnet-4-5-20250929",
+    "promptTemplate": "You are CTO..."
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "budgetMonthlyCents": 0,
+  "sourceIssueId": "uuid-or-null",
+  "sourceIssueIds": ["uuid-1", "uuid-2"]
+}
+```
+
+Response:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "pending_approval"
+  },
+  "approval": {
+    "id": "uuid",
+    "type": "hire_agent",
+    "status": "pending",
+    "payload": {
+      "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
+    }
+  }
+}
+```
+
+If company setting disables required approval, `approval` is `null` and the agent is created as `idle`.
+
+`desiredSkills` accepts company skill ids, canonical keys, or a unique slug. The server resolves and stores canonical company skill keys.
+
+## Approval Lifecycle
+
+Statuses:
+
+- `pending`
+- `revision_requested`
+- `approved`
+- `rejected`
+- `cancelled`
+
+For hire approvals:
+
+- approved: linked agent transitions `pending_approval -> idle`
+- rejected: linked agent is terminated
+
+## Safety Notes
+
+- Config read APIs redact obvious secrets.
+- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
+- All actions are logged in activity for auditability.
+- Use markdown in issue/approval comments and include links to approval, agent, and source issue.
+- After approval resolution, requester may be woken with `FIDELIOS_APPROVAL_ID` and should reconcile linked issues.

package/skills/fidelios-create-plugin/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: fidelios-create-plugin
+description: >
+  Create new FideliOS plugins with the current alpha SDK/runtime. Use when
+  scaffolding a plugin package, adding a new example plugin, or updating plugin
+  authoring docs. Covers the supported worker/UI surface, route conventions,
+  scaffold flow, and verification steps.
+---
+
+# Create a FideliOS Plugin
+
+Use this skill when the task is to create, scaffold, or document a FideliOS plugin.
+
+## 1. Ground rules
+
+Read these first when needed:
+
+1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
+2. `packages/plugins/sdk/README.md`
+3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+
+Current runtime assumptions:
+
+- plugin workers are trusted code
+- plugin UI is trusted same-origin host code
+- worker APIs are capability-gated
+- plugin UI is not sandboxed by manifest capabilities
+- no host-provided shared plugin UI component kit yet
+- `ctx.assets` is not supported in the current runtime
+
+## 2. Preferred workflow
+
+Use the scaffold package instead of hand-writing the boilerplate:
+
+```bash
+pnpm --filter @fideliosai/create-fidelios-plugin build
+node packages/plugins/create-fidelios-plugin/dist/index.js <npm-package-name> --output <target-dir>
+```
+
+For a plugin that lives outside the FideliOS repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.fidelios-sdk/`:
+
+```bash
+pnpm --filter @fideliosai/create-fidelios-plugin build
+node packages/plugins/create-fidelios-plugin/dist/index.js @acme/plugin-name \
+  --output /absolute/path/to/plugin-repos \
+  --sdk-path /absolute/path/to/fidelios/packages/plugins/sdk
+```
+
+Recommended target inside this repo:
+
+- `packages/plugins/examples/` for example plugins
+- another `packages/plugins/<name>/` folder if it is becoming a real package
+
+## 3. After scaffolding
+
+Check and adjust:
+
+- `src/manifest.ts`
+- `src/worker.ts`
+- `src/ui/index.tsx`
+- `tests/plugin.spec.ts`
+- `package.json`
+
+Make sure the plugin:
+
+- declares only supported capabilities
+- does not use `ctx.assets`
+- does not import host UI component stubs
+- keeps UI self-contained
+- uses `routePath` only on `page` slots
+- is installed into FideliOS from an absolute local path during development
+
+## 4. If the plugin should appear in the app
+
+For bundled example/discoverable behavior, update the relevant host wiring:
+
+- bundled example list in `server/src/routes/plugins.ts`
+- any docs that list in-repo examples
+
+Only do this if the user wants the plugin surfaced as a bundled example.
+
+## 5. Verification
+
+Always run:
+
+```bash
+pnpm --filter <plugin-package> typecheck
+pnpm --filter <plugin-package> test
+pnpm --filter <plugin-package> build
+```
+
+If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+
+## 6. Documentation expectations
+
+When authoring or updating plugin docs:
+
+- distinguish current implementation from future spec ideas
+- be explicit about the trusted-code model
+- do not promise host UI components or asset APIs
+- prefer npm-package deployment guidance over repo-local workflows for production

package/skills/para-memory-files/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: para-memory-files
+description: >
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/skills/para-memory-files/references/schemas.md

@@ -0,0 +1,35 @@
+# Schemas and Memory Decay
+
+## Atomic Fact Schema (items.yaml)
+
+```yaml
+- id: entity-001
+  fact: "The actual fact"
+  category: relationship | milestone | status | preference
+  timestamp: "YYYY-MM-DD"
+  source: "YYYY-MM-DD"
+  status: active # active | superseded
+  superseded_by: null # e.g. entity-002
+  related_entities:
+    - companies/acme
+    - people/jeff
+  last_accessed: "YYYY-MM-DD"
+  access_count: 0
+```
+
+## Memory Decay
+
+Facts decay in retrieval priority over time so stale info does not crowd out recent context.
+
+**Access tracking:** When a fact is used in conversation, bump `access_count` and set `last_accessed` to today. During heartbeat extraction, scan the session for referenced entity facts and update their access metadata.
+
+**Recency tiers (for summary.md rewriting):**
+
+- **Hot** (accessed in last 7 days) -- include prominently in summary.md.
+- **Warm** (8-30 days ago) -- include at lower priority.
+- **Cold** (30+ days or never accessed) -- omit from summary.md. Still in items.yaml, retrievable on demand.
+- High `access_count` resists decay -- frequently used facts stay warm longer.
+
+**Weekly synthesis:** Sort by recency tier, then by access_count within tier. Cold facts drop out of the summary but remain in items.yaml. Accessing a cold fact reheats it.
+
+No deletion. Decay only affects retrieval priority via summary.md curation. The full record always lives in items.yaml.