A base document for our next conversation · 2026-04-18

Two foundations.
One system worth building together.

okuro (黒) + agent-kernel — for Daniel

How to read this

Both agent-kernel and okuro exist because the same problem keeps showing up: AI assistants that do not behave consistently, do not remember what they learned, and do not carry the organization's standards from one project to the next. Each project answers that problem at a different layer of the stack. Each answers it well.

This is not a verdict

This document is a shared map drafted as a starting point for our next working session. Every claim is offered for challenge. Where I have a strong view, I flag it so you can push back. The goal is to walk into a whiteboard with the same vocabulary — not to decide anything from a PDF.

For Daniel

You built the kernel because the problems you see every day — consistent engineering standards, curated domain knowledge, zero-install portability, IDE-native activation — are real, and your solution is exactly right for them.

I built okuro because the problems I see every day — cross-project memory, multi-provider routing, non-engineering domains, cognitive personalization — are also real, and my solution is shaped for those.

The interesting question is not "which one?" — it is where do these two foundations overlap, where do they differ by design, and where would combining them compound each of our reaches? That is what the following pages try to map. Honestly. With your perspective deliberately in mind.

02 · How each is shaped

Two answers. Both correct
for what they solve.

Before any comparison, describe each in its own terms — the way its author would describe it on a napkin.

Agent-kernel

A curated, versioned convention layer for engineering teams.

kind: git repo of vetted markdown + rules + skills
runtime: none — pure content, zero install
consumer: the IDE's own agent (Cursor, Codex, Claude Code, VS Code)
activation: glob-triggered rules + description-matched skills
distribution: ak-copy.sh drops artifacts into each project
audit surface: git commits — every standard change is reviewable
center of gravity: curated depth in the engineer's workflow

Philosophy: the IDE already has excellent primitives. Don't reinvent them. Add the conventions that are missing.

Okuro

A persistent runtime layer that any agent can plug into.

kind: daemon + MCP server + SQLite+vec + role registry
runtime: Python + systemd user unit; stdio + HTTP MCP transports
consumer: any agent that speaks MCP — Claude, Codex, Gemini, Cursor, web chats, bots
activation: bootstrap() per session + semantic role/skill match
distribution: one install per host; adapters generate per-agent context
audit surface: session reports + compliance scorecard + tool telemetry
center of gravity: persistent state across sessions, agents, domains

Philosophy: the agent is the new runtime. Give it memory, roles, and a bridge so it can compound across sessions and providers.

How they coexist — one IDE, both stacks

Not in different rooms —
running in the same session.

┌─────────────────────────────────────────────────────────────────────┐
│   CURSOR · CLAUDE CODE · CODEX · VS CODE · WEB CHAT · ORCHESTRATOR  │
│        │                                   │                        │
│        │ (loads on boot)                   │ (MCP — any agent)      │
│        ▼                                   ▼                        │
│   AGENT-KERNEL                       OKURO MCP SERVER               │
│   .cursor/rules/  (static)           cortex · memory · roles        │
│   .claude/skills/ (static)           bootstrap · keyring · sysinfo  │
│   AGENTS.md       (static)           bridge_invoke  (orch. only) *  │
└─────────────────────────────────────────────────────────────────────┘
* bridge_invoke is an internal tool for okuro's orchestrator sub-tasks.
  Inside an IDE, the IDE's agent and model drive — the bridge is not called.

Important to say up front: okuro does not sit outside the IDE. The MCP server is reachable by every agent that speaks MCP — Cursor, Claude Code, Codex, VS Code, web chats. Inside an IDE, the kernel's static content loads as it does today, and the same agent can call okuro's MCP tools (cortex_search, read_memory, roles_match) alongside its native features.

The LLM bridge is used only by okuro's own orchestrator when it needs to fan-out a sub-task to a model — never as a replacement for the IDE's agent. Kernel is the content the IDE loads. Okuro is the tool surface the IDE's agent calls.

03 · What each emphasizes

Not better or worse —
differently invested.

Different centers of gravity

Neither is missing its opposite's properties accidentally — each is a design choice.

Axis	Agent-kernel emphasizes	Okuro emphasizes
Representation	human-readable markdown, reviewable in a git diff	runtime surface — MCP tools callable by any agent
State	stateless by design — every session re-reads the source of truth	persistent — memory, thoughts, progress, compliance
Personalization	consistent for the whole team — no per-user drift	adapted per user — neurotype, format, principles
Domain coverage	deep in engineering — Java, TS, Quarkus, UX, k8s, GCP	broad primitives — roles across 11 domains
Codebase intel	delegated to the IDE's native indexer (trusted, proven)	own indexer (cortex) — exposed as MCP to any agent
LLM routing	agent-neutral — whichever model the IDE drives	same inside an IDE (IDE drives). Bridge is orchestrator-internal for sub-tasks only.
Secrets	convention-level guidance ("no hardcoded secrets")	keyring MCP tools — programmatic store
System awareness	out of scope — the IDE and OS provide this	in scope — sysinfo tools for GPU / docker / storage / ports
People model	out of scope by design	person_lens / person_match — adapts tone per recipient
Feedback loop	git history + PR reviews — human-driven	session reports + tool telemetry — agent-driven
Distribution	clone + copy — trivially adoptable, per project	install once per host; adapters emit per-agent context
Activation	glob-match rules — zero-effort, automatic	semantic role/skill match — flexible, cross-domain
Review workflows	first-class — java-review, ux-review with severity output	roles exist; no canonical review template yet
Install footprint	zero runtime — works in any environment	Python + SQLite + systemd — needs a host
Curated content	deep, vetted, versioned — 16 KB Java 2026 rules, Quarkus blueprint	thin on curated content; strong on primitives
Audit	every standard change = a commit; clean chain of evidence	telemetry + session compliance; export needs work

Agent-kernel invests in

Craftsmanship. Every artifact is written by someone who knows the domain, reviewed in a PR, and kept versioned. That is hard to replicate with generated content.

Okuro invests in

Plumbing. Memory, bridge, roles, bootstrap. Infrastructure that any agent or domain can sit on top of, without needing to re-author content per scope.

04 · Scope of audience

Kernel: focused by choice.
Okuro: broad by primitive.

Two halves of the same organization

The kernel is explicitly an engineering artifact. Java, TypeScript, frontend UX, k8s, AlloyDB, GCP. That focus is what makes it deep — every skill is curated for a specific workflow, by people who do that workflow every day. Trying to make the kernel serve marketing or legal would dilute the thing that makes it excellent.

Okuro started with a different question: what are the primitives that would let any domain benefit from an agent partner? Memory, roles, a bridge, a people-model, a system-info layer. Not deep content for any one domain — scaffolding that domains can grow on top of.

Neither is wrong. They are two halves of the same organization.

Three questions worth pressure-testing together

Who	What they need	How the combined system could answer
CEO	"What actually shipped this quarter? Which features are in flight?"	A cross-project read of code + memory + progress — kernel's rigour in engineering, okuro's plumbing for the read.
Sales	"Can we pitch the new API as ready, or is there risk?"	Grounded answer from the same codebase the engineers work from — not a second-hand paraphrase.
Marketing	"Launch post in a week — what does the feature actually do?"	Draft pulled from recent commits + kernel-style documentation conventions — consistent voice, current facts.

These are not questions the kernel is trying to answer — and that is the right call for the kernel's scope. They are questions that open up when the primitives sit next to it.

Design question for our conversation

Do we care about these non-engineering scenarios? If yes, the path is combining. If we decide the organization is fine with engineering-only agent-assistance (a legitimate choice), then both projects stay in their current lanes. This is a strategy call, not a tooling call — and it is worth making together.

05 · Indexing & retrieval

The richest conversation
between our two projects.

The open design question

You have a principled position against RAG — and I take that seriously. You are right that a lot of the hype around vector-backed code retrieval is solving a problem the IDE already solves, at the cost of hallucination risk, stale indices, and false confidence. The kernel's choice to delegate code-intelligence to the IDE's own index is the correct move for the kernel's scope.

Okuro made a different choice — not because IDE indexing is bad, but because okuro is trying to be reachable both inside and outside the IDE. Cursor, Claude Code, VS Code all speak MCP, so an agent inside those IDEs can call cortex_search alongside the IDE's native indexer. And a web chat, Slack bot, or slide drafter — which cannot reach the IDE's index at all — gets the same surface.

So cortex is not "okuro instead of the IDE index". It is an additional reachable surface. Inside an IDE, both can coexist — the IDE's index for precise code work, cortex for cross-project or cross-session queries. Outside the IDE, cortex is simply what's available. The real question is whether we agree on when each is the right tool — and whether there is a shape that honors both.

Two intentional choices — honest tradeoffs

Agent-kernel — delegate to the IDE's index

Why it is a strong choice:

the IDE's index is already excellent, fresh, and sandboxed
no separate service to run, secure, or keep in sync
no hallucination risk from a lossy semantic layer
code never leaves the dev machine or IDE boundary
grep + LSP + IDE AST is strictly more precise than embeddings for code

The tradeoff: the index is scoped to the IDE session — an agent outside the IDE (or an orchestrator sub-task) cannot query it.

Okuro — cortex as an MCP surface

Why it is a different strong choice:

reachable from any MCP-speaking agent — inside or outside an IDE
one index per host, shared across projects, sessions, and providers
coexists with the IDE's native index rather than replacing it
exposes primitive operations (search / route / read_header) — the agent does the reasoning

The tradeoff: a separate index to maintain; a semantic layer adds a failure mode the IDE doesn't have; needs explicit freshness strategy.

Three scenarios that surface the tradeoff

1 — CEO

"Is the invoice-retry feature in development?"

Should the answer come from engineering (kernel path, human in the loop, accurate) or from an agent querying the index (faster, but grounded in what?). Both answers have merit.

2 — Sales

Auto-draft a pitch deck grounded in the actual API.

If the only indexer is inside the IDE, this workflow can't exist. Is that a constraint we accept, or a problem to solve?

3 — Marketing

Launch post before the PM writeup lands.

Is "wait for the PM" a feature (quality control) or a bottleneck (time-to-market)?

My honest position — offered for challenge

I think the answer is likely "both, bounded". Kernel's delegation to the IDE is right inside engineering — no semantic layer, no hallucination risk, IDE indexing is better than anything we could build. Okuro's cortex is right for non-IDE consumers — with guardrails (freshness, confidence, citations) that take the hallucination concern seriously. I want to hear where you'd push on this.

06 · Positioning for future models

Different investments survive
different futures.

Protocol changes · capability leaps · autonomy

Three ways the ground is likely to shift. Each approach has a coherent answer.

Protocol change (MCP v2 / A2A / something new)

Kernel's position

Markdown is protocol-agnostic. Any future agent that reads files still consumes the kernel. Zero migration cost. This is a real durability property.

Okuro's position

Transport is pluggable — stdio and HTTP already dual-shipped. New protocol = new adapter. Cost: one adapter per wave.

Model capability leap (longer context, built-in memory, reasoning-by-default)

Kernel's position

Bigger context = the model loads more of the kernel per session. The kernel benefits without changing anything. Passive compounding.

Okuro's position

Persistent memory + principles compound with reasoning-heavy models. The state layer gives smarter agents a frame. Active compounding.

Autonomous agents (act, don't just suggest)

Kernel's position

The IDE agent is the one taking action; the kernel tells it what policies to honor. Auditability is in the IDE's workflow (commits, reviews). Clean separation of concerns.

Okuro's position

Action tools + keyring + compliance scorecard give non-IDE agents a policy frame and audit trail. Covers consumers the IDE doesn't reach.

Combined view

Kernel is passively durable — it survives protocol changes almost for free. Okuro is actively adaptive — it compounds with new capabilities but needs maintenance. Together, the passive durability of kernel content + the active adaptation of okuro runtime gives the organization a better chance against any future wave than either alone.

07 · What each does brilliantly

Six strengths each.
All real.

Equal depth, both sides

Agent-kernel — what the kernel does that nothing else does

1 — Curated depth

The Java 2026 rules (rules/java.mdc) are 16 KB of real operational knowledge — Virtual Threads, Structured Concurrency, Loom over Reactive. This is craftsmanship, not prompt engineering.

2 — IDE-native activation

**/*.java → java.mdc is zero-effort, instant, and correct. Glob-triggered rules are elegant — they require nothing from the agent except loading the file.

3 — Zero runtime, zero lock-in

A markdown repo works in any environment, today and in ten years. No daemon, no DB, no migration path. Adoptable in regulated or air-gapped contexts without negotiation.

4 — Git-versioned audit trail

Every standard change is a commit. Reviewable. Revertable. Teachable. An auditor can answer "what was our Java policy on 2026-03-01" by reading git log. Hard to beat.

5 — Review workflows

The severity-ordered output in java-review / ux-review is product design applied to agent output. Crisp. Scannable. Actionable.

6 — Respects the IDE

Delegates to the IDE's own index, LSP, AST. Doesn't reinvent what works. This is a mature architectural choice — harder than it looks.

Okuro — what okuro does that nothing else does

1 — Persistent cross-session memory

Gotchas, decisions, architecture notes — survive across agent restarts, provider changes, and new sessions. Dedup + supersedes + confidence scoring make it trustworthy over time.

2 — Provider-agnostic bridge

One prompt routes to claude / gemini / codex / local based on capability. Zero API keys — uses the user's installed CLIs. Future model drops in as another bridge.

3 — Role library across 11 domains

56 expert roles — not just engineering. Designed as primitives so a marketing task and a code task use the same invocation shape.

4 — Cognitive personalization

Behavioral contract, neurotype, format preferences, principles — bootstrap once, every session starts with the user's brain modeled in.

5 — People model

person_lens adapts tone and content to a specific recipient. Communication is a first-class problem, not a prompt-crafting afterthought.

6 — Telemetry loop

Session reports, tool performance, compliance scorecard. Agent behavior is measurable — which is the foundation for improving it.

08 · Shapes of collaboration

Three shapes worth
putting on a whiteboard.

Not a recommendation — a menu

I have a lean, but I'd rather hear yours first.

Shape A — Parallel lanes (no integration, stay as-is)

idea

Kernel serves engineering. Okuro serves cross-domain / non-IDE. Each evolves on its own schedule. We agree on a boundary.

strengths

Zero coordination cost. Each project keeps its coherence. No premature coupling.

tradeoffs

Two vocabularies in the org. Some drift over time. Users at the seam may feel the split.

Shape B — Shared canon (content layer becomes common)

idea

Kernel repo stays as the authoring surface. Okuro imports its skills/rules/docs into canon registry. Adapters regenerate .cursor/, .claude/, AGENTS.md bundles identical to what the kernel produces today, and the same content is reachable as MCP tools from the same IDE agent (or any other consumer).

strengths

One source of truth for content. Kernel authors keep writing markdown. IDE agents keep loading static files and additionally can call the content as tools. Nothing breaks for existing kernel users.

tradeoffs

Needs a one-shot importer + per-project emitter. Canon schema must adopt kernel's YAML frontmatter to stay compatible.

Shape C — Full merge (one system)

idea

Deprecate one entry point. Everyone installs one thing.

strengths

Maximum consistency. One thing to learn.

tradeoffs

Hard sell in regulated envs. Breaks current IDE-native workflows. Loses the "zero install" property that makes kernel so adoptable. I would not advocate this — yet.

If Shape B is the one — what it would actually take

┌─────────────────────────────────────────────────────────────────────┐
│   AUTHORS (you + me + domain experts)                               │
│     │                                                               │
│     ▼                                                               │
│   AGENT-KERNEL REPO ◄─── authoring stays here, unchanged            │
│     │                                                               │
│     ▼ (one-shot import)                                             │
│   OKURO CANON REGISTRY                                              │
│     │                                                               │
│     ├──► emit .cursor/rules/   (loaded by IDE, identical to today)  │
│     ├──► emit .claude/skills/  (loaded by IDE, identical to today)  │
│     └──► MCP tools             (callable from the same IDE agent,   │
│                                 and from any non-IDE consumer)      │
└─────────────────────────────────────────────────────────────────────┘

Estimated effort to prove out: one weekend for a working importer, one more for the emitter. If it works, great. If it doesn't, we drop it and stay in Shape A — no damage done.

My lean — offered for push-back

Shape B feels like the right first step, because it preserves everything that works about the kernel and adds reach for the consumers okuro was built to serve. But I'm genuinely open to Shape A if you think B is overreach, or to something neither of us has drawn yet.

09 · Open questions for our whiteboard

What I want to hear
your take on.

Eight questions I do not have a closed answer to. These are the ones I think are worth a proper conversation.

1 — Indexing boundary

Where does the IDE's index stop being the right answer and a reachable index start being necessary? Is there a clean boundary, or is it per-use-case?

2 — RAG guardrails

If cortex stays, what guardrails would make it acceptable to you — citation requirements, freshness SLA, confidence thresholds, no-answer-when-uncertain?

3 — Authoring surface

Does markdown stay the source of truth for standards? If yes, we keep the kernel repo as the authoring frontend. If no, what replaces it?

4 — Org scope

Do we want non-engineering roles to have agent partners at all? If yes, what's the minimum viable content? If no, let's say so clearly.

5 — Schema convergence

Kernel's YAML frontmatter (name / description / relevant_when) vs okuro's canon shape. Should canon adopt yours as the public format? I lean yes.

6 — Glob rules

Glob-triggered passive rules are a property okuro does not have. Worth adding to canon? Your call — you designed the mechanism.

7 — Review workflows

The severity-ordered output format in java-review is excellent. Should it become a canon skill template that other reviews inherit?

8 — Regulated deployment

How do we support teams that cannot run a daemon or DB? A stateless CLI emit mode from canon would let those teams consume okuro content without installing okuro.

What I am explicitly not pre-deciding

The integration shape. The RAG question. Whether okuro or kernel is the "home" for shared content. Whether we even should integrate. Those are exactly the questions I want us to take to a whiteboard — not decisions for me to land on alone.

10 · Next step

When can we meet?

You built the kernel to solve real problems well.
I built okuro to solve different real problems well.
Neither is trying to replace the other. The organization
gets stronger if we shape the seam together.

What I'm proposing

60 minutes. Whiteboard or doc — whichever you prefer.
Agenda, if useful: walk indexing first (the hardest design question), then collaboration shapes, then the open questions.
No commitments up front. This is a design conversation, not a planning meeting.

Three ways to reply

"Yes — let's go." Pick a time. I'll come with a printed copy, a marker, and no prepared slides.
"Not yet." Send me the page you disagreed with most and I'll revise.
"I need more time." Take it. This document is not going anywhere.

The one thing I want you to take away

This document exists because I think your work is worth taking seriously and I want our two projects to compound rather than compete. Every claim I made is an invitation to be wrong. The only outcome I am optimizing for is a good conversation that leaves both projects stronger.

— Nicolas

Appendix A · What okuro actually ships

A complete feature overview,
from bootstrap to maintenance.

Everything below is running today against okuro.db. Each pillar is exposed as MCP tools, so any agent — Claude Code, Cursor, Codex, Gemini — uses the same surface. Nothing here is roadmap or marketing copy.

01 · Bridge

Zero-key LLM routing through your own CLIs.

Okuro owns no API keys. bridge_invoke() routes every prompt to an installed CLI subprocess (claude, gemini, codex, cursor) with a capability-aware routing table. Local inference via tm-inference is an optional accelerator, never a dependency.

02 · Bootstrap

One call delivers the full session packet.

Profile, principles, conventions, project state, relevant memories, tech stack, progress, and role catalogue — budgeted to ~13k tokens. Provider-native instruction files (~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.codex/instructions.md) are generated automatically, so every agent lands with the same context shape.

03 · Memory

Cross-agent persistent learnings.

Topic-tagged writes — gotcha / convention / decision / learning / architecture — stored once, read by every future session across every provider. Semantic retrieval via sqlite-vec. A gotcha Claude discovers at 10am is visible to Codex at 10:05.

04 · Cortex

A codebase index built for agents.

Semantic search, literal-regex cortex_search_code, file routing ("where does X live?"), header-first reads, section reads. Replaces blind grep/glob/full-file reads. Indexes run as a sidecar; agents hit the index, not the disk.

05 · Progress & Sessions

Every session leaves a trace.

Per-project progress log with summary → files → next-steps. Session compliance scoring tracks which tools were used and which mandatory checkpoints were hit. Tool telemetry feeds compliance_scorecard() — provider-vs-provider behavior over time.

06 · Thoughts & Todos

Capture the half-formed, surface the forgotten.

capture_thought parks ideas, observations, and questions without forcing structure. daily_digest resurfaces unresolved threads you'd otherwise lose. Full todo CRUD with status runs alongside — same store, different intent.

07 · Reminders

ADHD-aware, cascade by default.

set_reminder respects your active-hours windows. Snooze defaults to 15 minutes for the AuDHD profile. The system proposes reminders from observed patterns — you accept_suggestion or reject_suggestion, no silent auto-creation.

08 · People Lens

Communication guidance per human.

person_lens returns tone, formality, and prior-interaction hints for the specific person the agent is drafting to. person_match resolves "the frontend lead in Zurich" to a record. CRUD rounds it out.

09 · Expert Roles

56 roles across 11 domains, self-maintaining.

roles_match(task) picks the best expert for the job. Roles carry learnings (roles_knowledge) and refresh on a schedule — weekly / biweekly / monthly — so domain knowledge never ages silently. roles_maintenance exposes which roles are overdue.

10 · Keyring

Single-source secrets.

Every credential lives in okuro.keyring. Get, set, list, delete — no .env files, no hardcoded tokens, no creds in git history. Agents call keyring_get(name) and never see the value outside the process.

11 · Sysinfo

Machine state without shelling out.

GPU (sysinfo_gpu_status), storage, docker, free-port scanning, service health, and a combined sysinfo_system_overview. Replaces nvidia-smi, df -h, docker ps, curl localhost — with structured output an agent can reason about.

12 · Canon

Registry of tools and skills.

canon_list_tools / canon_list_skills expose the callable ground truth. canon_validate checks consistency — a skill that points at a missing tool fails here, not at runtime.

13 · Stack Governance

Approved choices, proposals, lint.

Per-project stack profiles (e.g., okuro-web-prod) list approved layers — language, framework, db, ops. stack_match(need) checks before install. New choices go through stack_propose → stack_decide_proposal. stack_lint_profile catches drift.

14 · Ingress & Inbox

External input, replayable.

ingress_ingest accepts input from outside channels (webhooks, voice, files). The inbox queue (inbox_list, inbox_replay) lets agents process new items idempotently and replay history when logic changes.

15 · Principles & Profile

Cognition as a first-class config.

13 working principles (DP01–DP09, SYS-*) govern agent behavior. The cognitive profile — neurotype, pet peeves, format preferences, active hours — drives UI adaptations (hierarchy, whitespace, action language) and appears verbatim in every bootstrap packet. One source of truth for "how this human prefers to work."

What's deliberately not here

No UI chrome, no chat front-end, no scheduler, no cloud sync. Okuro is a runtime layer — its job is to answer tools correctly. Presentation lives in whatever agent or app is calling.

Appendix B · Every tool is a question

The MCP surface,
read by what each tool answers.

~80 tools across 13 namespaces, all served from a single unified MCP server. The table below ignores signatures and instead names the question each tool answers — which is how agents actually pick them.

bootstrap · session entry

Tool	Question it answers
`bootstrap`	What's everything I need to start working — profile, principles, project state, memories, tools?
`brain_advise`	Can the local model give me a cheap briefing before I spend on a big CLI?
`get_profile` / `update_profile`	How does this human prefer to work — and can I update that?
`get_principles`	What working rules must I obey this session?
`run_maintenance`	Kick the hygiene cycle now.

cortex · codebase navigation

Tool	Question it answers
`cortex_search`	Where in the codebase does this concept live, even if the exact words aren't used?
`cortex_search_code`	Where is this exact string or regex?
`cortex_route`	What are the top 5 files for this concept?
`cortex_read_header`	What's this file about, and where are its sections?
`cortex_read_section`	What do lines A–B say, without loading the whole file?
`cortex_read_file`	Give me the whole file.
`cortex_navigate`	What else lives in this directory (up / down / siblings)?
`cortex_context`	Quick preview — header plus first 2000 chars.

sense · memory & knowledge

Tool	Question it answers
`write_memory`	I learned something non-obvious — remember it for every future agent.
`read_memory`	Has anyone already figured this out?
`capture_thought`	Park this half-formed idea for the user to revisit.
`search_thoughts`	What was that thing I was thinking about?
`update_thought`	Mark this idea done, or edit it.
`daily_digest`	What unresolved threads am I forgetting today?

sense · progress & projects

Tool	Question it answers
`log_progress`	Record what I just finished and what's next.
`get_progress`	Where did I leave off on project X?
`list_projects`	Which projects am I actively touching?
`get_project`	What's the setup for this project — path, stack, ports, roles?

sense · sessions & compliance

Tool	Question it answers
`session_report`	Mandatory exit: rate which tools I used and which actually helped.
`session_score`	How compliant is this session so far?
`session_history`	How have my recent sessions been going?
`tool_performance`	Which tools actually pay for themselves?
`compliance_scorecard`	Which provider behaves best over time?

sense · thoughts & todos

Tool	Question it answers
`create_todo`	Add a todo.
`list_todos`	What's on my plate?
`update_todo`	Change status or edit a todo.
`complete_todo`	Mark it done.
`drop_todo`	Forget it — no longer relevant.

sense · reminders

Tool	Question it answers
`set_reminder`	Remind me to do X at time T, with urgency and channel.
`list_reminders`	What's coming up?
`snooze_reminder`	Push this by 15 minutes (default for AuDHD profile).
`dismiss_reminder`	Kill it — I saw it, I'm not acting on it.
`acknowledge_reminder`	I'm on it.
`accept_suggestion` / `reject_suggestion`	Approve or deny a system-proposed reminder before it fires.

sense · people

Tool	Question it answers
`person_lens`	How should I talk to this person — tone, formality, prior context?
`person_match`	Who is the user describing?
`person_add` / `person_update`	Record or correct what I know about this human.
`person_get` / `person_list`	Fetch one / list all communication partners.

roles · expert catalogue

Tool	Question it answers
`roles_match`	Which expert should handle this task?
`roles_get`	Give me this role's full definition.
`roles_list`	Browse roles inside a domain.
`roles_domains`	What domains exist?
`roles_knowledge`	What has this role learned over time?
`roles_learn`	Teach this role something new.
`roles_maintenance`	Which roles are overdue for a refresh?

keyring · secrets

Tool	Question it answers
`keyring_get`	Fetch this secret.
`keyring_set`	Store this secret.
`keyring_list`	Which secret names exist (no values)?
`keyring_delete`	Remove this secret.

sysinfo · machine state

Tool	Question it answers
`sysinfo_gpu_status`	How are my GPUs — VRAM, temp, power, processes?
`sysinfo_storage_status`	Am I running out of disk?
`sysinfo_docker_status`	Which containers are up?
`sysinfo_port_status`	Which ports are free in this range?
`sysinfo_service_health`	Are my services responding to HTTP?
`sysinfo_system_overview`	One-shot: GPU + storage summary.

bridge · LLM routing

Tool	Question it answers
`bridge_invoke`	Route this prompt to the best installed CLI for the capability.
`bridge_providers`	Which CLIs are installed and authenticated?
`bridge_status`	Is the bridge healthy?
`bridge_transcribe`	Turn this audio into text.

canon · registry

Tool	Question it answers
`canon_list_tools` / `canon_get_tool`	What tools are registered, and what does this one declare?
`canon_list_skills` / `canon_get_skill`	What skills are registered, and what does this one declare?
`canon_validate`	Is the registry consistent (no dangling references)?

stack · tech stack governance

Tool	Question it answers
`stack_match`	Do we already have an approved choice for this need?
`stack_propose`	Propose a new stack choice with rationale.
`stack_decide_proposal`	Approve or reject a pending proposal.
`stack_list_proposals`	What proposals are pending?
`stack_profile` / `stack_profile_list`	Fetch / list stack profiles.
`stack_active_for_project`	Which profile is this project using?
`stack_assign_profile`	Assign a profile to a project.
`stack_list_layers` / `stack_list`	Browse stack layers and their choices.
`stack_get`	Full detail on a single stack choice.
`stack_set_status`	Update a choice (approved / deprecated / etc).
`stack_validate` / `stack_lint_profile`	Is the profile internally consistent — any drift or gaps?

ingress & inbox · external input

Tool	Question it answers
`ingress_ingest`	Capture this external input (webhook / voice / file) into the inbox.
`ingress_status`	Is the ingress pipeline healthy?
`inbox_list`	What's waiting for me to process?
`inbox_replay`	Re-run these items through processing (logic changed).

How agents actually use this

An agent doesn't memorise 80 tools. It reads the question-column until one matches its current need, then calls the tool. That's the entire mental model — and it's why bootstrap ships the full tool table into the context window on every session.

Appendix C · How an agent actually gets information

Every tool fires back
toward the agent at the centre.

The agent never reaches out to raw files, shells, or APIs. Each namespace is a satellite that answers one kind of question — pulses are the signal flowing from tool back to agent. Hover a node to spotlight it.

Bootstrap's measured cost, across every frontier model

The budget ceiling is 13k tokens. The actual payload is ~8,500 tokens — measured across four task variants on my live profile (range 8,297 – 8,580). Each row below is 100% = that model's full context window; the green slice is what bootstrap actually consumes.

Claude Opus 4.7 1M

8.5k / 1.0M0.9%

Gemini 2.5 Pro

8.5k / 1.0M0.9%

GPT-5.4

8.5k / 400k2.1%

Grok 4

8.5k / 256k3.3%

Claude Opus 4.7 std

8.5k / 200k4.3%

Claude Sonnet 4.6

8.5k / 200k4.3%

Claude Haiku 4.5

8.5k / 200k4.3%

DeepSeek V3.2

8.5k / 128k6.6%

bootstrap payload (~8.5k tokens measured) remaining context window

Measured on 2026-04-19 via okuro's own estimator (len(text) / 4, matching cl100k_base). Top consumers of that 8.5k: MCP tool table (~1,300), project + learnings (~1,100), cross-agent memories (~1,050), task-relevant memories (~650), tech stack (~600), behavioral contract (~560). Even on the tightest window — DeepSeek 128k — bootstrap leaves ~93% of the window free for the task. On a 1M model, it's under 1%.

01
Session opens. The agent calls bootstrap() and receives profile, principles, memories, stack, active project, and the full tool table — budgeted to ~13k tokens.
02
Question arrives. The agent matches its current need against each tool's question ("where does this live?" → cortex, "has this been solved?" → memory) instead of memorising signatures.
03
Tool fires inward. Structured data lands in the context window — never raw shell output, never blind file reads. Every response is agent-shaped, not human-shaped.
04
Session closes. log_progress(), write_memory(), and session_report() capture what was learned — so the next agent (any provider) doesn't start blind.

Why the diagram is radial, not hierarchical

Okuro is not a tree with the agent at the root. It's a hub of equal-standing namespaces that all answer inward. No namespace is "deeper" than another — they differ only in the question they own. Picking the right namespace is the agent's job; okuro's job is to keep each one cheap to call and correct by default.

Two foundations.One system worth building together.

For Daniel

Two answers. Both correctfor what they solve.

A curated, versioned convention layer for engineering teams.

A persistent runtime layer that any agent can plug into.

Not in different rooms —running in the same session.

Not better or worse —differently invested.

Kernel: focused by choice.Okuro: broad by primitive.

Three questions worth pressure-testing together

The richest conversationbetween our two projects.

Two intentional choices — honest tradeoffs

Three scenarios that surface the tradeoff

Different investments survivedifferent futures.

Protocol change (MCP v2 / A2A / something new)

Model capability leap (longer context, built-in memory, reasoning-by-default)

Autonomous agents (act, don't just suggest)

Six strengths each.All real.

Agent-kernel — what the kernel does that nothing else does

Okuro — what okuro does that nothing else does

Three shapes worthputting on a whiteboard.

If Shape B is the one — what it would actually take

What I want to hearyour take on.

When can we meet?

A complete feature overview,from bootstrap to maintenance.

Zero-key LLM routing through your own CLIs.

One call delivers the full session packet.

Cross-agent persistent learnings.

A codebase index built for agents.

Every session leaves a trace.

Capture the half-formed, surface the forgotten.

ADHD-aware, cascade by default.

Communication guidance per human.

56 roles across 11 domains, self-maintaining.

Single-source secrets.

Machine state without shelling out.

Registry of tools and skills.

Approved choices, proposals, lint.

External input, replayable.

Cognition as a first-class config.

The MCP surface,read by what each tool answers.

bootstrap · session entry

cortex · codebase navigation

sense · memory & knowledge

sense · progress & projects

sense · sessions & compliance

sense · thoughts & todos

sense · reminders

sense · people

roles · expert catalogue

keyring · secrets

sysinfo · machine state

bridge · LLM routing

canon · registry

stack · tech stack governance

ingress & inbox · external input

Every tool fires backtoward the agent at the centre.

Bootstrap's measured cost, across every frontier model

Two foundations.
One system worth building together.

Two answers. Both correct
for what they solve.

Not in different rooms —
running in the same session.

Not better or worse —
differently invested.

Kernel: focused by choice.
Okuro: broad by primitive.

The richest conversation
between our two projects.

Different investments survive
different futures.

Six strengths each.
All real.

Three shapes worth
putting on a whiteboard.

What I want to hear
your take on.

A complete feature overview,
from bootstrap to maintenance.

The MCP surface,
read by what each tool answers.

Every tool fires back
toward the agent at the centre.