craik 0.1.1

Governed agent-runtime substrate for case files, policy, receipts, prompt compilation, and provider transports.

Craik

Craik is a governed agent-runtime substrate: typed case files, policy envelopes, capability receipts, prompt compilation, pluggable provider transports, handoffs, and work graphs for durable project work.

The project is named after Kenneth Craik, whose work on mental models framed intelligence as the ability to build internal representations of the world and use them to reason before acting. Craik applies that idea to agent systems: agents should not operate as isolated prompt executions. They should work from shared, evidence-backed project models, leave durable handoffs, and act inside explicit governance boundaries.

Thesis

Most agent frameworks optimize for tool calling, prompt routing, or parallel execution. Those are necessary, but they are not enough for long-running work.

Craik is built around a different premise:

Agent systems become useful at organizational scale when they can remember, justify, coordinate, dispute, and hand off work over time.

Craik treats memory, provenance, policy, and work state as runtime concerns rather than optional logging.

What Works Today

Craik can assemble local repository context, read optional GitHub and Stigmem state, compile governed runner prompts, execute fixture-backed and live-shaped provider requests through OpenAI Responses, Anthropic Messages, and OpenAI-compatible Chat Completions adapters, persist receipts/handoffs/work graphs, and propose memory updates for review.

The live provider path is explicit. Runtime callers opt into live access, supply provider metadata, and resolve credentials through typed credential profiles or credential pools. The local OpenAI-compatible provider path can target a localhost /v1 server such as Ollama for optional live validation without paid API keys.

Craik authenticates to provider APIs through typed credential profiles. Profile kinds include env-var API keys, local-CLI OAuth fallback (e.g. reading ~/.claude/.credentials.json), vendor CLI subprocess bridges, external secret manager references, and Stigmem-backed credential references. A credential pool supports rotation and failover across multiple profiles.

Craik authenticates the operator via OIDC against any compliant IdP. Device-code and loopback+PKCE flows are both supported; craik login initiates the flow, craik whoami reports the active operator, craik logout revokes the session. Every provider call is bound to both an operator identity and a credential identity; every receipt names both. Workload-identity providers (GitHub Actions, Kubernetes projected tokens, generic file/env-var) plus RFC 8693 token exchange enable credential-less deployment in CI and cloud.

Policy envelopes can constrain which operators and which credentials a task may use. First-time use of a credential profile is approval-gated and produces a receipted authorization chain. Credential expiry surfaces as evidence in case files so long-running runs are warned about tokens that will expire mid-work.

What Does Not Work Yet

Craik is not yet a fully autonomous release-quality agent. It does not claim unbounded tool execution, unattended file edits, broad remote Stigmem writes, or production multi-agent orchestration. Tool execution is policy-bound, and live provider calls remain opt-in rather than hidden CI behavior.

Vision

The long-term direction is a durable agent operating layer where agents work from shared project state, leave auditable handoffs, resolve contradictions, and coordinate across memory, policy, tools, issues, and release workflows.

Relationship to Stigmem

Craik is a separate product and repository from Stigmem.

• Stigmem is the durable memory and truth substrate: facts, provenance, scopes, trust, federation, auth, and plugin hooks.
• Craik is the agent operating layer: orchestration, context assembly, handoffs, work graphs, capability policy, receipts, and user workflows.

Craik can run in degraded local mode without Stigmem for demos and development, but Stigmem is the reference substrate for real team use.

Agent Integration Model

Craik core is runner-agnostic. The current MVP path provides deterministic OpenAI- and Anthropic-shaped provider runner execution for certification and offline validation. Preview prompt-handoff adapters are also available for:

• Codex
• Claude
• Gemini

Each runner path consumes the same Craik contracts: project case file, policy envelope, capability grants, worker result, receipts, handoff, and memory proposals.

Craik is not built as a dependency layer on another agent framework. It borrows broadly useful product patterns such as gateway ergonomics, workspace identity, persistent sessions, typed tools, skills, and channel integrations while keeping Craik's first agent path focused on direct runner adapters.

Core Ideas

• Shared project models: Agents receive a task-specific model of the project before acting.
• Durable handoffs: Agent runs end with machine-readable state for the next agent.
• Fact-grounded context: Context is assembled from evidence, ADRs, repo state, issues, docs, and memory.
• Governed execution: Tool access, write authority, review gates, and documentation obligations are policy-controlled.
• Capability receipts: Important actions produce structured records of actor, target, reason, and result.
• Contradiction handling: Conflicting facts are surfaced for resolution instead of silently overwritten.
• Work graph: Tasks, PRs, issues, facts, decisions, docs, tools, agents, and artifacts are modeled as connected state.

Planning Docs

• Documentation Index
• Vision
• Architecture Decisions
• Product Strategy
• Differentiators
• Architecture
• Runtime Contracts
• Case Files
• Project Model
• Governance
• Intent Locks
• Handoffs
• Receipts
• Feature Specification
• MVP Plan
• Implementation Plan
• Roadmap
• Governance Model
• Stigmem Integration
• Installation
• Quickstart
• Configuring Craik Home
• Project Registry
• Using Case Files
• Agent Onboarding
• GitHub Adapter
• Stigmem Documentation Demo
• Work Graph
• Scope Control
• Writing Handoffs
• Memory Proposals
• Memory Diffs
• Memory Impact Preview
• Contradiction Inbox
• Connecting Stigmem
• Evidence And Assumptions
• Context Budgeting
• Development Checks
• CLI Reference
• Schema Reference
• Policy Profiles
• Memory Backends
• Memory And Stigmem
• Stigmem Compatibility
• Fail-Open
• Capability Grants
• Running Policy Tests
• Redaction
• Local State Layout
• Local Store
• Config Reference
• Project Profile
• Policy Tests
• GitHub Config
• Graph Export
• Self-Audit
• Secrets
• Limitations

Current Status

Craik is moving toward a robust 0.x.0 MVP release. 1.0.0 is a later stability signal, not the first release target.

The repository now includes the CLI package, strict runtime contracts, local SQLite state, project/task/case-file workflows, policy and receipt primitives, runner preview contracts, governed loop fixtures, multi-agent review contracts, instruction distillation, quality/recovery helpers, skills/plugins foundations, operator view formatters, gateway/channel contracts, sandbox/provider routing contracts, learning-loop helpers, multimodal decisions, migration/i18n contracts, and broad docs/tests through the v0.12 roadmap.

The remaining MVP work is to harden these contract and helper surfaces into one complete release-quality workflow: remote Stigmem write promotion, God-file/runtime package cleanup, ADR-backed design decisions, and docs/test depth comparable to Stigmem. Package version 0.1.0 marks the first governed provider, credential, and operator-identity substrate; roadmap sections remain implementation gates, not 1.0.0 readiness claims. See Robust MVP Roadmap.

Implementation Stack

Craik core is implemented in Python 3.12/3.13 with a CLI-first package shape. The initial stack is:

• Python 3.12 or 3.13
• Typer for CLI
• Pydantic for runtime contracts
• SQLite for local persistent state
• stdlib HTTP for the first Stigmem and GitHub compatibility clients
• pytest for tests
• ruff and mypy for quality gates

TypeScript remains appropriate for future UI, gateway adapters, and channel integrations, but it is not the initial core runtime stack.

Package and CLI Naming

Craik uses the same name across the public repository, Python package, import module, and CLI command:

• GitHub repository: eidetic-labs/craik
• PyPI distribution: craik
• Python module: craik
• CLI command: craik
• Future npm package, if needed: craik

Live registry checks on 2026-05-15 showed craik available on both PyPI and npm. If a registry race occurs before publication, craik-runtime is the fallback distribution name while preserving craik as the CLI command and Python module.

Local State

Craik uses a single product-home directory by default:

~/.craik/

The location can be overridden with:

CRAIK_HOME=/custom/path

Craik should keep different data classes separated inside that home:

~/.craik/
  config/
  secrets/
  state/
  cache/
  logs/
  receipts/
  handoffs/
  case-files/
  projects/

Project-local .craik/ directories are opt-in only. Craik should not silently create project-local metadata inside repositories.

License

Craik is released under the MIT License. The license choice is intended to match the permissive adoption pattern used by comparable agent frameworks while keeping Eidetic Labs trademarks and branding separate from the code license.

Project Governance

• Contributions: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security disclosure: SECURITY.md
• Trademark and brand usage: TRADEMARKS.md
• Maintainer and release policy: MAINTAINERS.md

Initial Build Target

The first implementation should focus on a repository-aware CLI runtime:

1. Create a project profile for a local Git repository.
2. Connect optional Stigmem memory.
3. Assemble a task case file from repository state, docs, issues, policies, and facts.
4. Execute a governed single-agent task with scoped capabilities.
5. Record capability receipts.
6. Produce a structured handoff.
7. Propose fact updates for future agents.

Multi-agent orchestration, work graph visualization, contradiction inbox, and plugin probation should be layered on after the single-agent durable workflow is working end to end.

First Demo Target

Craik's first real demo target is Stigmem documentation and state reconciliation. The initial runnable version is exposed through craik demo stigmem-docs.

The demo should:

1. Register the Stigmem repository as a Craik project.
2. Connect to a local Stigmem node.
3. Create a docs reconciliation task.
4. Assemble a case file from repository state, ADRs, public docs, GitHub issues/PRs, recent Stigmem facts, and prior handoffs.
5. Identify stale or contradictory documentation.
6. Produce proposed documentation updates.
7. Record capability receipts for important actions.
8. Generate a durable handoff.
9. Propose or write new Stigmem facts.
10. Export a work graph for the task.

This target is intentionally based on a real workflow that already exposed the need for durable memory, public/internal doc boundaries, ADR constraints, and agent handoffs.