kioku AGENTS.md

Kioku agent operating manual

This file defines how coding agents must work in sandovaldavid/kioku. It is an operational guide for the current develop branch, not a roadmap or historical report.

Repository scope

Kioku is a .NET 10 Model Context Protocol server that reads and writes an Obsidian vault. The server supports local stdio and authenticated Streamable HTTP transports. The optional Obsidian bridge plugin is maintained and released independently in sandovaldavid/kioku-obsidian.

The server accesses the vault filesystem directly. Obsidian does not need to be open for core note, search, project, session, indexing, or coordination operations. A running Obsidian application and plugin are required only for operations registered through the optional bridge and plugin capability groups.

This repository owns:

• the MCP server, contracts, prompts, resources, and integrations;
• vault indexing, retrieval, filesystem policy, work sessions, and engineering workflows;
• server packaging, Docker deployment, CI, releases, retrieval evaluation, and public documentation.

This repository does not own the Obsidian plugin source or its release workflow.

Source-of-truth order

When statements disagree, use this precedence:

1. current code and configuration on the target branch;
2. executable tests and generated public contracts;
3. maintained operational documentation;
4. merged pull requests and closed issues as historical evidence only;
5. open issues, proposals, plans, and comments as non-implemented intent.

Never describe an issue, roadmap item, proposed architecture, benchmark expectation, or PR body as implemented unless the target branch contains the corresponding code or generated contract.

Current verified snapshot

• Target framework: net10.0, configured in Directory.Build.props.
• Solution: Kioku.slnx.
• Latest published server package: 3.1.2. The integration branch can contain unreleased changes beyond that release.
• MCP C# SDK packages: ModelContextProtocol and ModelContextProtocol.AspNetCore 2.2.0.
• MCP protocol baseline: 2026-07-28.
• Streamable HTTP runs explicitly with Stateless = true; local stdio remains supported.
• Default MCP profile: 45 tools.
• All-capabilities profile: 78 tools.
• Engineering projects support first-class spec documents through create_engineering_spec; create_implementation_plan can link a same-project spec, and get_project_context accepts spec / specs aliases.
• New project scaffolds create decisions, bugs, specs, plans, knowledge, sessions, and backlog eagerly; daily and tickets remain supported optional/lazy workflows.
• Optional groups disabled by default: research, generation, css, assets, bridge, plugin, and coordination.
• Supported client integrations: Claude Code, Codex, OpenCode, GitHub Copilot, and Antigravity via native client MCP registration.
• The generated docs/commands-reference.md is authoritative for tool names, schemas, annotations, prompts, resources, and profile counts.
• The generated docs/configuration-reference.md is authoritative for public process configuration.
• Markdown files in the vault are the durable source of truth. Runtime indexes and the embeddings cache are derived data; there are no database migrations to maintain.