Knowledge layer

Annotations, @orkai source tags, and graph-enriched code views — how orkai makes indexed code understandable to AI agents.

Indexing turns files into searchable code entities — functions, classes, modules, and more. The knowledge layer adds three things on top of raw source: AI-generated annotations, author-written @orkai tags in comments, and an enriched source view that injects graph relationships directly into the code your agent reads. Together they let an assistant understand what code does, why it was written that way, and what else it connects to — without re-parsing the whole repo on every query.

Annotations

When annotations are enabled, the daemon runs a background pipeline after indexing. For each code symbol it can create up to two annotation entities — regular orkai entities linked back to the source via an annotates relation.

Annotations are eventually consistent: indexing returns immediately; generation runs in the background. When source code changes, annotations become stale and are regenerated on the next index (the daemon compares content hashes). Smarter agents — or you — can refine annotations over time via MCP; the event log tracks changes.

Parent symbols (packages, modules, classes) are annotated first; child symbols inherit that context when their own annotations are generated. A function inside a billing package gets better purpose text because the package annotation is already in the prompt.

Enable annotations

Annotations are controlled in daemon config (~/.orkai/config.yaml), not per index run. See Configuration § annotations for the full key list. Restart the daemon after changing config.

orkai config set annotations.enabled true
orkai config set annotations.provider ollama
orkai config set annotations.model qwen2.5-coder:7b-instruct

After enabling, re-index your project so the pipeline has entities to annotate:

orkai index .
# Re-run annotation jobs without a full re-index:
orkai index --annotations-only .

Read annotations

From the CLI:

orkai get <code-entity-id> --annotations

From MCP (Cursor, Claude Desktop, etc.): search_code with include_annotations: true returns inline annotation text on each hit. annotations(action: "list", entity_id: "...") lists annotations for one symbol; annotations(action: "create", ...) lets an agent upsert a purpose or insight layer directly.

@orkai source tags

Tags are author intent in source comments. During orkai index the indexer parses @orkai:* lines attached to a symbol and stores them as metadata or graph edges — paid once at index time, not on every agent query.

Place tags in line comments immediately above the symbol (or inside its doc comment block):

// @orkai:decision This function avoids goroutines because write order matters
// @orkai:ref(id=d5a003d1f642f03946ac5f3798e77569)
// @orkai:ref(id=abc123def45678901234567890123456, chunk=section-chunk-id)
func runIndex() {
    // ...
}

Supported comment prefixes: //, #, *, and block-comment lines.

@orkai:decision

Free-text explanation of why the code is written this way.

• Stored on the code entity as metadata.author_decisions (array of strings).
• Not a graph edge — there is no target entity.
• Fed into the insight annotation prompt when annotations are enabled.

Multiple @orkai:decision lines on one symbol append to the array.

@orkai:ref

Link from this symbol to any existing orkai entity (standard, skill, document, task, etc.).

// @orkai:ref(id=<entity-id>[, chunk=<chunk-id>])

• id is required — a 32-character hex entity ID already in the daemon.
• chunk is optional — stored on the edge for section-level navigation without loading the full parent entity.
• Stored as a references_entity graph edge from the code symbol to the target.
• At index time the daemon validates the ID exists. Unknown IDs produce a visible warning in the index summary — refs are never silently dropped.

Tags must appear in comment lines directly above the symbol's start line, with no blank non-comment lines between the tag block and the symbol. Re-index after adding or changing tags.

Enriched source view

Beyond annotations and tags, orkai precomputes a graph-enriched view of each code symbol at index time and stores it separately from pristine source. This is not a second field in API responses — the daemon returns one raw string plus an enriched boolean so agents do not pay twice the tokens.

The enriched view contains:

1. A short [orkai] header explaining the payload is graph-enriched, not pristine source.
2. Synthetic @ref lines inserted immediately above matching source lines — from uses_type edges (resolved types → entity IDs; unresolved e.g. stdlib → no indexed entity) and references_entity edges from @orkai:ref tags (up to 20 hints per symbol).
3. The pristine source lines unchanged — refs are prepended above the matching line, not edited in-place.

Example snippet an agent might see in search results:

// [orkai] Enriched view: @ref lines below are graph-derived (uses_type, references_entity), not source comments.
// For change-risk context. Pristine source: search_code(..., enrich=false) or entity(action:"get", id="...", enrich=false).
// @ref uses_type *sql.DB → entity(id=abc123..., file=internal/db/pool.go) (line 42)
// @ref references_entity Revenue Policy → entity(id=d5a003d1..., file=docs/policy.md)
func calculateRevenue(db *sql.DB) error {
    // ...
}

Defaults and overrides

Re-index after graph or tag changes so the stored enriched view stays current. Type references and @orkai:ref edges are resolved at index time — query-time enrichment is not recomputed.

Typical workflow

1. Enable annotations in daemon config if you want AI-generated layers.
2. Index your project — orkai init then orkai index .
3. Add @orkai:decision and @orkai:ref tags where maintainer context or cross-links matter; re-index.
4. Let your agent use search_code (enriched by default) for navigation; pass include_annotations: true when it needs purpose/insight text inline.
5. Refine insight annotations via MCP when the LLM missed something important — especially after you add new @orkai:decision tags.

The web UI (orkai open) shows annotations grouped by purpose and insight on each code entity's detail page.