Spiral Knowledge Format (SKF)

What's in an SKF file?

An SKF v1.2 file contains everything Spiral knows about a project:

• Facts — Typed knowledge entries (stack, decisions, features, constraints, APIs, etc.) with temporal validity windows
• Relationships — Typed edges between facts (depends_on, implements, contradicts, etc.)
• Episodes — Provenance records tracing every fact to its source (which extraction, chat, or import created it)
• Rules — Project governance rules that travel with the knowledge

Example

{
  "skf_version": "1.2",
  "exported_at": "2026-03-29T10:00:00Z",
  "project": {
    "name": "my-saas",
    "description": "B2B analytics platform"
  },
  "facts": [
    {
      "key": "stack.frontend",
      "category": "stack",
      "layer": "core",
      "value": "Next.js 15 with App Router",
      "confidence": 0.95,
      "valid_from": "2026-01-15T00:00:00Z",
      "valid_until": null
    }
  ],
  "relationships": [
    {
      "from_key": "feature.billing",
      "to_key": "decision.database",
      "type": "depends_on"
    }
  ],
  "episodes": [
    {
      "type": "deep_extraction",
      "timestamp": "2026-03-29T10:00:00Z",
      "actor": "spiral-cli"
    }
  ],
  "rules": [
    {
      "name": "decisions-need-rationale",
      "enforcement": "soft"
    }
  ]
}

Importing

Import parses each entry into typed facts, creates relationships, records provenance episodes, and applies any governance rules. Existing facts with the same key are preserved — import is additive, never destructive.

Exporting

Export your full knowledge base — all active facts, relationships, and rules — as a portable SKF file. Use this for backups, migrations between instances, or sharing with others.

Bring Your Own Agent (BYOA)

You can generate SKF files using any AI tool — you don't need Spiral's AI features:

1. Run spiral extract --prompt-only to get the extraction prompt
2. Paste into Cursor, Claude, ChatGPT, or any AI with your codebase open
3. Save the structured output as .skf.json
4. Import: spiral import output.skf.json

Version history