OKF Knowledge Format Integration

Full specification: 00-product-spec.md

Positioning

OKF v0.1 is the storage source of truth for Memory and Knowledge. PostgreSQL is a retrieval index built from OKF files.

Upstream AI can either:

• query through MCP over PostgreSQL (recommended, faster), or
• read OKF files directly (for example ${paths.contexts}/shared/knowledge/projects/my-project.md)

Directory Convention

OKF files live under paths.contexts (defaults to ~/.yzos/contexts/). A single machine can use default/; multiple devices use work/, personal/, and shared/ (see 12-multi-device.md).

The path is configurable in config.yaml. In PostgreSQL, okf_files.path stores either a path relative to paths.contexts or an absolute path.

${paths.home}/
  contexts/                     # paths.contexts
    default/                    # single-machine default (or work/personal/shared for multi-device)
      knowledge/                 # Knowledge Bundle
        index.md
        projects/
        ai-work/                # crystallized AI tool work summaries
        ...
      memory/
        index.md
        user_insight/
        ...
      entities/                 # person / project / task OKF records
        person/
        project/
        task/
    shared/                     # optional multi-device sync area
      ...
  exports/                      # cron rollup output
    daily/2026-06-27.md
    weekly/2026-W26.md
  observations/                 # L4 raw observation data (not OKF, not synced by default)
  entity_overrides/             # manual overrides (L2, can be synced)
  sync.toml

YZOS Concept Types

Knowledge

type	Description
Project	Project overview
Technical Insight	Technical findings
AI Work Summary	Summary of AI tool work sessions
Playbook	Operational runbook
Reference	Archived external documentation
Infrastructure	Infrastructure knowledge
Voice Summary	Voice conversation summary
Entity Person	Person record (entities/person/)
Entity Project	Project record (entities/project/)
Entity Task	Task record (entities/task/)

AI Work Summary example

---
type: AI Work Summary
title: Fixed the SAML callback URL in Claude Code
description: Fixed the SAML authentication callback URL configuration in an example project.
tool: claude-code
project: example-project
resource: ai-session:ai-claude-20260627-143022
tags: [saml, auth, example-project]
timestamp: 2026-06-27T15:45:00Z
---

# What was done

Fixed the SAML callback URL missing its base_url prefix, and exposed a use_absolute_acs_url flag on the frontend.

# Tool use summary

- Edit `src/auth/saml.py`, added base_url prefix logic
- Bash `pytest tests/auth/`, all tests passed

# Related

- Belongs to [Example Project](/projects/example-project.md)

Memory

Dimensions are unchanged: user_insight | topic_highlight | deep_user_model | custom.

There is no agentic_memory dimension. AI behavioral preferences are managed by each upstream AI tool itself; YZOS only observes and crystallizes their work output.

Cron Maintenance and OKF

Maintenance jobs operate on OKF files directly:

Job	OKF operation
kb_reorganize	Merge similar Knowledge entries, fix broken links, update index.md
rollup_daily	Write exports/daily/YYYY-MM-DD.md
rollup_weekly	Write exports/weekly/YYYY-Www.md
reconcile	Scan OKF hashes and reconcile against PostgreSQL

Rollup files also follow the OKF format and can be read directly by upstream AI.

Sync with PostgreSQL

Write path: Triage -> OKF .md file -> Indexer -> PostgreSQL chunks.

Maintenance path: cron reconcile scans OKF and rebuilds any missing PostgreSQL index entries.

External edits: a file watcher detects mtime changes and triggers re-indexing.

Import Sources

Source	Maps to
Claude Code project CLAUDE.md	Knowledge Reference
AI tool session logs	Knowledge ai-work/
Manual Markdown	knowledge/ or memory/custom/

Knowledge Graph

OKF cross-links are stored in the okf_links table and rendered with Cytoscape.js in the review UI. Upstream AI retrieves a subgraph through the MCP yzos_knowledge_graph tool.