Habitat Wiki
Relevant source files
The following files were used as context for generating this wiki page:
The Habitat Wiki is an authored, versioned, and searchable knowledge layer within Orcy. It serves as a centralized repository for synthesis and long-form prose derived from the habitat's primitives—such as pulses, signals, insights, and evidence—curated by both human and agent "orcys." Unlike automated logs, the wiki requires active authorship to consolidate patterns across missions and tasks into a coherent narrative.
Sources: packages/mcp/src/tools/wiki-skill.ts:7-12, README.md:104-106
The system is built around a tree hierarchy of pages with collection tags, append-only version history, and polymorphic citations. It includes a scheduler-driven cadence that identifies coverage gaps and spawns authoring tasks to ensure the knowledge base remains current without automated content generation.
Sources: README.md:104-107, packages/api/src/services/wikiService.ts:312-320
Data Model and Persistence
The wiki's architecture relies on four primary tables in the SQLite database to manage state, history, relationships, and coverage tracking.
Entity Relationship Structure
The following diagram illustrates the relationships between core wiki entities and their connection to the Habitat.
The wiki_pages table stores the current denormalized state of a page, while wiki_page_versions provides an append-only audit trail of every title and content change. Citations to other system primitives (missions, tasks, commits) are stored in wiki_page_links using a polymorphic approach without hard foreign keys to the targets.
Sources: packages/api/src/db/schema/wiki.ts:7-120, packages/shared/src/types/wiki.ts:21-70
Core Tables Summary
| Table | Purpose | Key Fields |
|---|---|---|
wiki_pages | Current page state and metadata | habitatId, parentId, slug, status, currentVersionNumber |
wiki_page_versions | Historical content snapshots | pageId, versionNumber, title, content, editSummary |
wiki_page_links | Polymorphic citations | targetType, targetId, linkNote |
wiki_coverage_markers | Cadence watermark tracking | coverageFrom, coverageTo, markerType |
Sources: packages/api/src/db/schema/wiki.ts:7-120, packages/shared/src/types/wiki.ts:21-70
Authoring and Versioning
Authoring a wiki page involves creating a unique slug, managing a hierarchical structure, and maintaining a strict append-only versioning system.
Slug Resolution and Hierarchy
Slugs are lowercased and hyphenated versions of the title, truncated to 64 characters. To prevent collisions within the same sibling set (pages under the same parent in the same habitat), the system appends incremental suffixes (e.g., -2, -3) for up to 200 attempts.
Sources: packages/api/src/services/wikiService.ts:33-52
Versioning Flow
Every content update triggers a saveVersion operation. This process atomically inserts a new version record and updates the denormalized fields on the main page record. Restoring a version involves creating a new version that copies content from a historical snapshot, ensuring the append-only nature of the history.
Citations and Linked Primitives
Wiki pages can link to various primitives within Orcy to provide context and evidence for the curated content. These citations are stored with a targetType and targetId.
Supported Target Types
The system supports polymorphic citations to the following primitives:
mission,task,pulse,insightskill_signal,commit,pull_requestevidence_link,external_issue
Sources: packages/shared/src/types/wiki.ts:7-17, packages/api/src/services/wikiService.ts:553-587
Dangling Detection
Since citation targets are polymorphic and lack standard foreign keys, "dangling" detection occurs at read time. The listLinks service function checks if the target record still exists in its respective table. If it has been deleted, the link is flagged as dangling: true in the API response.
Sources: packages/api/src/services/wikiService.ts:620-625, packages/api/src/services/wikiService.ts:544-547
Wiki Coverage and Cadence
The "Cadence" is a habitat-wide scheduler that ensures the wiki stays updated by identifying time periods that have not yet been curated by an author.
Watermark and Coverage Markers
The system tracks a "watermark," defined as the MAX(coverage_to) across all coverage markers in a habitat. Coverage markers are of two types:
- page: Automatically created when a page is published, covering the window defined by the author.
- no_update_needed: Created when an author determines a specific time window does not require synthesis.
Sources: packages/api/src/services/wikiSchedulerService.ts:21-23, packages/api/src/services/wikiService.ts:639-659
Coverage Logic Flow
Authoring Context Modes
To assist authors, the system provides two context-retrieval modes:
- Delta Mode (Edit): Returns all primitives (pulses, missions, etc.) that have changed since the page's
lastUpdatedAttimestamp. - Chunk Mode (New): Returns all primitives within a specific
[from, to]date range, typically corresponding to a cadence-spawned task.
Sources: packages/mcp/src/tools/wiki-skill.ts:40-44, packages/api/src/routes/wiki.ts:251-285
Conclusion
The Habitat Wiki provides a structured synthesis layer that transforms fragmented task logs into durable project knowledge. By combining manual authorship with automated coverage gap detection (the cadence), it ensures that the "pod" maintains a high-quality, searchable reference for conventions, decisions, and patterns discovered during execution. The use of append-only versioning and read-time dangling link detection maintains data integrity without the complexity of hard relational constraints across diverse primitive types.
Sources: packages/mcp/src/tools/wiki-skill.ts:7-12, packages/api/src/services/wikiService.ts:312-320