Company world model, capabilities, and intelligence
This document is the contract for how “what the company knows” and “what runs” fit together. It exists so the console, agents rail, and issues stay one game: Postgres Company OS keyed by company_id, not a parallel in-memory product.
Knowledge representation (JSON-LD): knowledge-representation.md — @context, table→type map, promotion ladder ↔ memory_edges. Export one memory: GET /api/company/companies/{company_id}/memory/{memory_id}/export-jsonld.
1. World model (company) — canonical operational graph
Treat Postgres Company OS as the single source of operational truth for a company:
| Area | Role in the graph |
|---|---|
| Tasks | Work units: state, checkout, requires_human, attachments, context_notes, capability_refs (links to skills/SOPs/tools/packs/agents), spawn/handoffs, spend links. |
| Runs / telemetry | Honest signals: terminal status, tool usage, logs — surfaced on tasks and in governance-style events where wired. |
company_memory_entries | Durable shared and agent-scoped facts; search/append via API and tools. |
companies.context_markdown | Company-wide narrative the LLM layer always sees (with memory and task context). |
GET …/tasks/:id/llm-context | Composed read model for agents: context markdown, memory pool, task block, workforce profile, headings/TOC as implemented. |
| Goals, governance events, spend | Alignment, policy trail, and cost — same company_id. |
Anything labeled “intelligence” in product terms should read and write through this graph (or explicitly sync into it), not maintain a second ledger the UI pretends is equally real.
2. Capabilities — atomic building blocks
These are already modular in the product; the rule is to link them into the world model, not float them beside it:
- Tools & skills — registered and invoked with company/task context.
- Packs — bootstrap templates; after import, roster and skills should resolve to Postgres (
company_agents, adapter config, etc.). - Workforce agents — rows with roles, budgets, profiles;
llm-contextand task checkout should resolve persona → agent row where possible. - SOPs / playbooks — procedures tied to projects and tasks (see playbooks-projects-and-visions.md).
Direction: task and agent APIs (and UIs) should carry explicit references (IDs, personas, skill refs) so the graph is queryable — “who is on this,” “what skills apply,” “which SOP governs this stream.”
Implemented in tree: tasks.capability_refs (JSONB array of { "kind", "ref" } or create-body strings normalized to kind: skill). Set at create, PATCH /api/company/tasks/{id}/context, and bundle import/export; copied to spawned subtasks; merged into GET …/tasks/{id}/llm-context and the Intelligence workflow feed when updated (task_capability_refs_updated). Pack bridge: POST …/import-paperclip-home pulls on-disk agents/skills into Postgres for the company.
Paperclip → Postgres (goals & DRIs): goals.paperclip_goal_id + paperclip_snapshot for upserts; POST /api/company/companies/{id}/sync/paperclip-goals (optional JSON { "goals": [...] }, or empty body when hsm_console runs with in-process IntelligenceLayer); POST …/sync/paperclip-dris same for { "dris": [...] }. dri_assignments table + GET/POST …/dri-assignments and PATCH/DELETE …/dri-assignments/{row_id} for first-class org DRIs (including manual rows).
3. Intelligence layer — two APIs, one truth
| Surface | Scope | Use |
|---|---|---|
/api/company/companies/{company_id}/… | Per company | Canonical: goals, tasks, memory, spend, intelligence summary, llm-context, etc. |
/api/paperclip/* (proxied in dev) | Global / in-memory demo | Optional: composition, routing experiments, demos — not a second company dashboard of record. |
Allowed patterns:
- Embed composition/routing inside Company OS (per
company_id) so all state lives in Postgres; or - Sync Paperclip-style state into Postgres (goals, signals, DRIs) so operators still have one store and one UI truth.
Anti-pattern: two first-class UIs that each imply their own goals/signals/registry without migration or sync — that splits hierarchy (alignment, backlog, who is on what) across “Postgres truth” and “optional global layer.”
Workspace Intelligence in the company console should prefer GET …/intelligence/summary (and related company routes), not Paperclip-only views.
4. Interfaces — edges of the same model
| Interface | Expectation |
|---|---|
| Company console | Reads/writes /api/company/… for the selected company; copy should not imply a global parallel state is authoritative. |
| Agents rail | Chat and task actions mutate the same task graph (checkout, notes, runs) for that company_id. |
| Issues / my-work | Same task list and states as the API; no shadow issue system. |
If a feature cannot point at a company_id and a concrete row or API path, it is not yet part of the world model — it is integration or demo debt.
5. Implemented alignment contract
This section is the quick check for whether a feature helps models, harnesses, and systems stay "likewise" — seeing the same world through different interfaces instead of inventing parallel realities.
| Contract | Implemented surface | Why it matters |
|---|---|---|
| Model context contract | GET /api/company/tasks/:task_id/llm-context in src/company_os/agents.rs returns company_id, hsmii_home, context_notes, capability_refs, workspace paths, agent_run_profile, combined_system_addon, section byte counts, and context_manifest. | A model starts from the same company/task graph the UI and tools use. It can see explicit memory/tool instructions rather than guessing from chat. |
| Memory contract | company_memory_entries plus company_memory_search / company_memory_append in src/tools/company_os_tools.rs; shared, agent, and broadcast scopes are exposed in llm-context. | Shared facts compound across agents; private notes stay scoped; urgent company lines can be broadcast without becoming invisible side-channel state. |
| Capability contract | tasks.capability_refs (skill, sop, tool, pack, agent, etc.) set through task APIs/imports and rendered in llm-context + workflow feeds. | Models and harnesses can reason over explicit procedures and tools, not prose-only hints. |
| Governance / DRI contract | requires_human, dri_assignments, governance_events, run feedback, and intelligence summary workflow feed. | Escalation and accountability become rows with owners and evidence, not vibe-based chat conclusions. |
| Intelligence sync contract | Paperclip-style goals/DRIs sync into Postgres via paperclip_goal_id, paperclip_snapshot, sync/paperclip-goals, sync/paperclip-dris, and manual DRI CRUD. | External intelligence can compose and propose while Company OS remains the ledger. |
| Harness contract | hsm-eval, hsm_meta_harness, hsm_outer_loop, Python scripts/meta-harness, scripts/refiner-jsonl-pass.py, and scripts/meta-harness/company_os_refiner_pass.py write artifact trees, turns_hsm.jsonl, company_os_turns.jsonl, candidate configs, and deltas. | Evals and live agent-chat smokes improve benchmark/runtime policy through reviewable evidence; they do not silently mutate live runtime behavior. |
| Eval-pack contract | schemas/company_eval_pack.v1.json, scripts/meta-harness/pack_loader.py, and scripts/meta-harness/kpi_verifier.py let each company declare tasks, personas, scorer bindings, KPI assertions, and promotion thresholds. | Company-specific "what good looks like" stays declarative while runner, tracing, verifier registry, frontier search, and promotion gates remain shared platform primitives. |
| Hosted / LLM documentation contract | docs-site/sync-manifest.json mirrors selected docs into VitePress pages and /llm/*.md files. | Agents can fetch the same architecture contract operators read, reducing prompt drift across tools and sessions. |
Four knowledge layers
Treat company knowledge in four layers (constitution → operational → procedure → evidence). Full table, JSON-LD mapping, DRI/verifier/ledger rules, and context/review/compaction policy: knowledge-representation.md.
Promotion ladder
Use this ladder whenever a new intelligence feature, harness result, or agent behavior is introduced:
- Observe: capture the signal in a trace, task note, governance event, memory row, or run artifact.
- Bind: attach it to a company, task, DRI, goal, capability ref, or harness config path.
- Expose: make it visible through
llm-context,intelligence/summary, task APIs, or an eval artifact index. - Verify: run the relevant smoke or benchmark and record the artifact path / logs.
- Promote: only after verification, map the change into runtime config, prompt policy, tool allowlist, memory policy, or docs.
If a step cannot be completed, label the work as integration debt rather than "implemented intelligence."
Red flags
- A model answer depends on state that is not in
llm-context, memory, task notes, or a declared file path. - A dashboard shows goals, agents, DRIs, or task state without a
company_idand Company OS API path. - A harness
best_config.jsonis treated as production behavior without a runtime mapping. - A high-stakes action completes without
requires_human, DRI, governance, or run evidence when confidence is low. - A capability is described in copy but absent from
capability_refs, tool registry, skills, SOPs, or pack import.
See also
- Intelligence layer & DRI alignment — composer vs ledger vs edge (DRIs); integration checklist for external intelligence.
- Company eval packs and meta-harness scoring — declarative per-company task/KPI packs and shared scorer/promotion contract.
- HSM-II field coordination — stigmergic field, model/harness/runtime contract, and ratchet gates.
- Memory, workspace attachments, shared context —
company_memory,context_notes,llm-context, tools. - Playbooks, projects, and visions — how SOPs sit on the task/project graph.