Core Concepts

Projection Engine

Different AI agents read context in different formats. Spiral generates targeted configuration files for each IDE from your unified knowledge graph — one source of truth, multiple projections.

Generated files

When you run spiral pull, spiral sync, or the MCP sync_context tool, the projection engine queries your knowledge graph and writes these files:

CONTEXT.md— The universal context file. Read by every AI agent.
.cursor/rules— Cursor-specific AI rules matched to your detected stack.
CLAUDE.md— System prompt context for Claude-based agents.
.github/copilot-instructions.md— Context instructions for GitHub Copilot.
.windsurfrules— Context hooks for Windsurf Cascade.
.agents/skills/spiral-context/SKILL.md— Context as an agent skill file.

Additionally, spiral init and spiral clone also generate .cursor/mcp.json and .vscode/mcp.json for MCP connectivity.

How it works

All projection files are derived from structured memory — the facts in your knowledge graph. They are regenerated deterministically, meaning the same facts always produce the same files. This is the foundation of Spiral's consistency guarantee: every IDE sees the same truth.

Manual edits

Projection files are generated, not hand-edited. If you edit CONTEXT.md or .cursor/rules locally, your changes become a proposal on the next sync — they don't silently override the knowledge graph. To change context permanently, update the facts via spiral push or the MCP memory_upsert_fact_v1 tool.