Recall and Read

Recall and Read

Recall is the retrieval entry point for Threadnote. It is a search step, not the final payload: it returns candidate viking:// URIs plus abstracts, and you then read or list the chosen URI to get the actual content.

Recall is a search step

recall matches a query against local OpenViking context and returns candidate viking:// URIs along with short abstracts. Those URIs are pointers, not the data itself:

• Read the chosen URI to get its content.
• List a directory when the returned node is an abstract or overview rather than a leaf memory.

Do not treat the recall result as the answer. Pick the relevant pointer, then read or list it.

threadnote recall --query "agent context"
threadnote read viking://agent/threadnote/memories/.abstract.md
threadnote list viking://agent/threadnote/memories --all --recursive

Scope inference and enrichment

Recall infers scope from the query so you do not have to spell out every path.

• Repo/skill scope inference. Queries like skills for api service infer a repo or skill scope. When the query mentions a seeded project name, recall runs a parallel scoped pass against viking://resources/repos/<project>, so personal memories and seeded project documentation come back in the same response. Include the repo or project name as a token in the query to make this pass fire.
• Override the inference. Use --uri to pin the scope to a specific subtree, or --no-infer-scope to disable inference entirely.
• Branch enrichment. Queries that mention this branch or current branch are enriched with local git and workspace terms when they are available, so recall can resolve branch and workspace context.
• Archived lifecycle paths. Exact memory and resource matches skip archived lifecycle paths by default. Pass --include-archived to include archived handoffs and incidents.
• Cleanup nudges. When many active handoffs or overlapping returned memories surface, recall nudges scoped cleanup so you can compact before they accrete.

threadnote recall --query "skills for api service"
threadnote recall --query "latest handoff for this branch"
threadnote recall --query "threadnote lifecycle storage"
threadnote recall --query "threadnote lifecycle storage" --include-archived

Treat seeded resources under viking://resources/repos/<project> as the canonical source for "how does this repo do X" (README, AGENTS.md, CLAUDE.md, SKILL.md, docs). Treat personal memories as in-flight or per-author context layered on top.

CLI

Command	Purpose
recall --query "<text>"	Search context; returns candidate viking:// URIs plus abstracts.
read <viking-uri>	Read a single URI returned by recall or list.
list <viking-uri> / ls <viking-uri>	List a viking:// directory. Add --all --recursive to walk the subtree.

threadnote recall --query "durable feature knowledge for this branch"
threadnote read viking://agent/threadnote/memories/.abstract.md
threadnote list viking://agent/threadnote/memories --all --recursive

MCP

When MCP is installed, prefer the Threadnote-named tools: recall_context first, then read_context or list_context. Always pass JSON arguments.

For queries that say "current repo" or "this branch", pass the current workspace path as callerCwd so Threadnote resolves branch and workspace terms from the right directory instead of guessing from the MCP server's launch directory.

recall_context({"query": "agent context"})
recall_context({"query": "current repo latest handoff", "callerCwd": "/absolute/workspace/path"})
read_context({"uri": "viking://agent/threadnote/memories/.abstract.md"})
list_context({"uri": "viking://agent/threadnote/memories"})

Older adapters expose the compatibility aliases search, read, and list. They take the same query argument; only the tool names differ.

search({"query": "agent context"})

Shared memory auto-sync

Before recall and read return, Threadnote auto-syncs clean incoming shared-memory updates when a configured share repo is behind. This applies to MCP recall_context / read_context and CLI threadnote recall / threadnote read.

• Threadnote does a periodic background git fetch for configured share teams. If a shared repo is behind, it rebases the clean worktree, reindexes the pulled markdown into OpenViking, and then returns the requested result.
• Failures degrade to warnings. The local read still continues with the best local data available.
• Automatic sync never commits a dirty shared worktree. For a dirty worktree, a git conflict, or an explicit push, run threadnote share sync after resolving local state.

See also: Memory Lifecycle, Seeding Repos and Skills, Sharing Memories, CLI Reference.