Agent Instructions

Agent Instructions

threadnote install writes managed, user-level agent guidance into the instruction files for Codex, Claude Code, Cursor, and GitHub Copilot. This page documents where that guidance lives and the behavior it asks agents to follow. Repo files stay authoritative; this guidance is the cross-agent floor that sits on top of them.

Where It Is Installed

threadnote install upserts a managed block into each supported agent's user-level instruction file. Personal content in those files is preserved — only the managed block is written or refreshed.

Agent	Instruction file
Codex (CLI)	~/.codex/AGENTS.md
Claude Code	~/.claude/CLAUDE.md
Cursor	~/.cursor/rules/threadnote.md
GitHub Copilot (VS Code)	~/.copilot/instructions/threadnote.instructions.md

These files are the cross-agent guidance floor: they ask agents to recall context, store handoffs, and maintain durable memories, and they work for every supported agent by relying on the agent to comply.

For deterministic moments where the agent should not have to remember, Claude Code can also install agent-side hooks (PreCompact auto-snapshot handoff and SessionStart context preload/update banner). Codex, Cursor, and Copilot hook installs are no-ops that print a clear explanation, because those agents do not expose a hook surface today. See Configuration for the hook install commands.

Shared Context

Repo files remain authoritative. Always follow the nearest AGENTS.md, CLAUDE.md, or other checked-in instruction file first. Use OpenViking through Threadnote as a shared local context and memory layer on top of those files, not as a replacement.

When OpenViking MCP tools are available, use them directly. Prefer the Threadnote-named MCP tools when present:

• recall_context
• read_context
• list_context
• remember_context
• compact_context
• share_publish

Always pass JSON arguments to MCP tools. When a recall query says "current repo" or "this branch", include the current workspace path as callerCwd so Threadnote resolves branch and workspace terms instead of guessing from the MCP server's launch directory.

recall_context({"query":"current repo latest handoff","callerCwd":"/absolute/workspace/path"})

Older Threadnote MCP adapters expose the aliases search, read, list, and store instead. If MCP is unavailable, fall back to the threadnote CLI.

Recall At Task Start

At the start of a non-trivial task, recall relevant context before making changes. Search for:

• the current repo and branch;
• recent handoffs;
• durable feature memories for the branch, feature name, project/topic, or issue;
• seeded project guidance under viking://resources/repos/<project> — README, AGENTS.md, CLAUDE.md, SKILL.md, docs — for canonical conventions, test commands, release process, on-call runbooks, and anything the team checked into the repo;
• task-specific skills or workflow guidance;
• user or team preferences that may affect the work.

Include the repo or project name as a token in the recall query so the project-guidance pass fires. recall_context runs a parallel scoped search against viking://resources/repos/<project> whenever the query mentions a seeded project name, so memories and project documentation come back in the same response. Treat seeded resources as the canonical source for "how does this repo do X" and personal memories as in-flight or per-author context layered on top.

When a recalled handoff describes an active branch or feature, do a second recall for durable memories about that feature before coding. The handoff tells you the current work state; durable feature memories tell you the design, decisions, invariants, interfaces, and gotchas that should survive beyond one session.

Skip proactive recall for tiny one-shot questions where context would add noise.

Search results are not the final payload. Treat returned viking:// URIs as pointers: read the relevant URI, or list a directory when the result is an abstract or overview node. See Recall and Read for the full search-then-read flow.

Remember

When the user asks you to remember something, store it — unless it contains secrets, credentials, customer data, production logs, or other sensitive data.

Also remember durable workflow facts you discover during work when they would help future agents and are not already in canonical docs. Prefer updating checked-in docs for canonical repo rules.

During feature work on a branch, maintain durable feature knowledge in addition to handoffs. Store or update a durable memory when you learn something future agents should know about the feature itself: intended behavior, design decisions, API contracts, data flow, migration semantics, edge cases, known limitations, or why an implementation choice was made. Do not wait until the end of the branch — update the feature memory whenever a valuable change lands or a decision becomes clear.

Use lifecycle metadata when storing memories:

• kind: durable for facts future agents should use by default.
• kind: handoff for current work logs and next steps.
• project for the repo/product namespace.
• topic for the active issue or stable fact. Reusing the same project/topic keeps one current memory updated.

If a durable feature memory already exists, update it in place with the same project/topic or with --replace <uri> / replaceUri instead of creating a new timestamped durable memory for every small progress note. When replaceUri points at a shared durable/ URI, Threadnote updates that shared memory in place and pushes the shared repo — do not create a personal replacement and then run share_publish again. See Memory Lifecycle for the full model.

Memory Compaction

When working on the same active issue, keep one current-state memory updated instead of creating many small progress memories. Prefer project/topic storage over timestamped memories when the issue has a stable name.

When recall or read surfaces several memories that describe the same durable fact, incident, branch, or handoff, run a scoped hygiene dry-run before deciding what to change:

threadnote compact --project my-repo --topic active-bug --dry-run

compact_context({"project":"my-repo","topic":"active-bug","dryRun":true})

• Store one concise replacement memory that preserves the current status, the important facts, and the source viking:// URIs you merged.
• Use threadnote archive <uri> when the old handoff still has provenance value but should no longer be treated as current context.
• Remove superseded duplicates with threadnote forget <uri> only when they are clearly redundant or stale and contain no unique useful detail.
• Keep hygiene scoped to the current project/topic. Do not run global cleanup.
• If the memories disagree or you are not sure what can be deleted, keep them and mention the possible cleanup instead.

Never compact secrets, credentials, customer data, raw production logs, or checked-in canonical docs into memory.

Sharing

Publish a durable memory when its content is useful to other engineers working on the same project (intended behavior, design decisions, API contracts, gotchas) and is safe to share. Do NOT publish:

• handoffs or anything carrying machine-local paths, branch state, or in-flight task context;
• memories under memories/preferences/;
• anything mentioning secrets, customer data, raw logs, or material a teammate's git history should not carry.

share_publish runs the same scrubber as the CLI, writes and pushes the shared copy first, then removes the personal copy after the push succeeds. Before publishing, confirm with the user unless they have already instructed you to share durable memories autonomously. Only durable/ memories are shareable. See Sharing Memories for the publish-time scrubber rules and team-repo workflow.

Handoff

Before pausing, switching agents, or ending meaningful work with local changes, store a concise handoff. Include:

• repo and branch;
• related durable feature memory URI or topic, when known;
• files touched;
• current status;
• tests or checks run;
• blockers;
• next suggested step.

If you wrote or read multiple memories for the same project/topic during the task, run a scoped hygiene dry-run before the handoff. Do not do global memory cleanup. Do not store long diffs, secrets, raw logs, or customer data in handoffs.

CLI Fallback

Use these only when MCP tools are not available:

threadnote recall --query "last handoff for this branch"
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
threadnote remember --kind durable --project example --topic active-issue --text "Feature knowledge..."
threadnote remember --replace viking://user/example/memories/durable/projects/example/workflow.md --text "Updated durable engineering note..."
threadnote compact --project example --topic active-issue --dry-run
threadnote archive viking://user/example/memories/handoffs/active/example/old-issue.md
threadnote forget viking://user/example/memories/handoffs/archived/example/duplicate.md
threadnote handoff --project example --topic active-issue --task "short task summary" --tests "checks run" --next-step "what to do next"

See also

Memory Lifecycle, Recall and Read, Sharing Memories, Migration