Concepts and FAQ

Concepts and FAQ

A glossary of the terms threadnote uses, plus answers to the questions that come up most when people first wire it into their agents. For the full picture of any concept, follow the cross-links into the dedicated pages.

Part A — Concepts

OpenViking

The local context and memory store threadnote wraps. OpenViking is a separate project (openviking.ai); threadnote pins version 0.3.12 and installs openviking[local-embed]==0.3.12. Its local server, openviking-server, binds to 127.0.0.1:1933 (Python, uv-managed). threadnote is the thin, agent-neutral workflow on top — it does not reimplement the store. See Architecture.

viking:// URI

The stable address scheme for everything in the store. A viking:// URI is a pointer, not the content: recall returns URIs and abstracts, and the agent then reads or lists the one it wants. Examples:

viking://user/<you>/memories/durable/projects/<project>/<topic>.md
viking://user/<you>/memories/handoffs/active/<project>/<topic>.md
viking://resources/repos/<project>
viking://agent/<agent-id>/memories/.abstract.md

A given URI is the same pointer from every session, agent, and worktree. See Recall and Read.

Account / user / agent-id

Three identity values OpenViking uses to namespace content, all configurable via environment:

Value	Env var	Default	Role
Account	THREADNOTE_ACCOUNT	local	Top-level storage partition on disk
User	THREADNOTE_USER	local username	Owner of viking://user/<you>/memories/...
Agent id	THREADNOTE_AGENT_ID	threadnote	Shared agent identity for viking://agent/<agent-id>/memories

Personal memories live under the user subtree; the shared agent identity gives every supported agent a common namespace. See Configuration.

Memory kind: durable vs handoff

The two kinds of memory record:

• kind: durable — feature knowledge meant to outlive the session: design decisions, API contracts, intended behavior, gotchas. It is the default for threadnote remember, and it is the only kind that is shareable.
• kind: handoff — current work logs: repo, branch, files touched, tests run, blockers, next step. It is what the next agent recalls first. threadnote handoff captures git state for it.

During branch work you typically keep one of each side by side under the same project/topic. See Memory Lifecycle.

Status: active vs archived

A memory is either active (in the default recall scope) or archived (kept for provenance, out of the default scope). threadnote archive <uri> copies a memory into the archived lifecycle tree, then removes the original after the archive write succeeds; recall finds it again only with --include-archived. Archive an old handoff when it still has historical value but should stop being treated as current context. See Memory Lifecycle.

Project + topic (stable lifecycle path)

A project (repo/product namespace) plus a topic (active issue or stable fact) resolve to one stable file path. Reusing the same pair means later updates replace the current version in place instead of accreting timestamped notes. Bare threadnote handoff uses the current repo and current git branch as project/topic. Pass --timestamped only when you intentionally want a historical note.

threadnote remember --kind durable --project my-repo --topic feature-x --text "..."
threadnote handoff --project my-repo --topic feature-x --task "Current status for feature X"

Seed manifest

The curated list of repo paths threadnote is allowed to import. threadnote init-manifest --repo <path> creates or updates ~/.openviking/seed-manifest.yaml; threadnote seed imports only the paths declared there. There is no whole-repo indexing — the manifest is the boundary. The bundled config/seed-manifest.example.yaml is only an example. See Seeding Repos and Skills.

resources/repos (seeded guidance)

Where seeded repo guidance lands: viking://resources/repos/<project>. This subtree holds the curated docs you imported — README, AGENTS.md, CLAUDE.md, SKILL.md, docs/** — and is treated as the canonical answer to "how does this repo do X". Personal memories layer in-flight or per-author context on top. When a recall query names a seeded project, recall runs a parallel scoped pass against this subtree. See Seeding Repos and Skills.

Team / shared namespace

The opt-in path for sharing durable memories with a team git repo: viking://user/<you>/memories/shared/<team>/.... Only memories you explicitly publish leave the machine; personal handoffs, preferences, and unpublished durables always stay local. Only durable/ memories are shareable. Incoming shared memories are normally fetched and synced automatically before recall/read returns. See Sharing Memories.

The publish scrubber

The secret scanner that runs on every publish, in both the CLI and the share_publish MCP tool. It refuses to publish a memory containing common secret patterns: PEM private keys, sk-..., gh[pousr]_..., Bearer ..., AKIA..., and xox[abprs]-.... Publish is transactional — it writes and pushes the shared copy first, then removes the personal copy only after the push succeeds, so you never end up half-published. See Safety and Security.

MCP stdio adapter

The bundled bridge that connects agents to the store. The binary is threadnote-mcp-server, registered as a stdio MCP server. stdio is the default because OpenViking 0.3.12 does not expose a native /mcp HTTP route. Threadnote-named tools are recall_context, read_context, list_context, remember_context, compact_context, and share_publish; older adapters expose the aliases search, read, list, and store. Always pass JSON arguments.

codex mcp add threadnote -- threadnote-mcp-server
claude mcp add threadnote -- threadnote-mcp-server

See Architecture and CLI Reference.

Agent hooks (PreCompact / SessionStart)

Deterministic agent-side hooks, installed for Claude Code only today (the only supported agent that exposes a hook surface). Codex, Cursor, and Copilot hook installs are no-ops that print a clear explanation.

• PreCompact auto-stores a handoff snapshot for the current repo right before Claude compacts the conversation, so the next turn can recall it even if no manual handoff was written.
• SessionStart preloads the latest handoff/feature memory for the current repo into the new session and prints a one-line [threadnote] vX.Y.Z available; run threadnote update banner when the installed version is behind.

Hooks complement, not replace, the instruction files: the soft guidance covers semantic decisions; hooks cover deterministic moments the agent shouldn't be trusted to remember. See Agent Instructions.

Context compaction

Two related meanings:

• Conversation compaction — when an agent's context window fills and the conversation is summarized. Durable facts get lost in the summary, which is why the next turn recalls the durable memory and handoff (and why the Claude PreCompact hook snapshots first).
• Memory compaction — scoped hygiene over overlapping active memories via threadnote compact / compact_context. It dry-runs by default; applying archives stale handoffs, forgets only exact duplicates, and leaves ambiguous durable or incident memories for manual review.

See Memory Lifecycle.

Part B — FAQ

Why not just CLAUDE.md / AGENTS.md?

Use them. threadnote is not a replacement. The split is simple: put durable repo policy in the .md files; put feature knowledge, task history, handoffs, and personal workflow facts in threadnote. Instruction files are the right place for stable, canonical, version-controlled rules. They are the wrong place for living context — what happened last session, which branch is mid-refactor, which on-call workaround actually shipped — because that history makes them noisy, stale, and expensive to load into every context window.

	CLAUDE.md / AGENTS.md / Cursor rules	threadnote
Where it lives	In the repo, versioned, shared via PR	Local OpenViking store, cross-repo, cross-agent; optionally published to a team git repo
Best for	Coding standards, test commands, review rules, architecture invariants	Feature knowledge, handoffs, branch state, on-call findings, personal workflow facts
Read pattern	Loaded into every agent context window in this repo	Recalled on demand; only the relevant URIs enter the window
Edit cost	Human writes, PR review, high friction (by design)	Agents write, humans guide, low friction
Lifecycle	Long-lived; stale entries hurt every session	durable / handoff / archived; compact in place, never accrete

Does it index my whole repo?

No. Seeding is manifest-scoped: threadnote seed imports only the paths declared in the seed manifest, never the whole repository. threadnote is intentionally scoped to curated docs, memories, skills, and handoffs — it is not a source-navigation replacement. See Seeding Repos and Skills.

Does anything leave my machine?

No, not until you act. Every remember and handoff writes under THREADNOTE_HOME (defaults to ~/.openviking). The only egress path is share publish on a curated durable memory to a team git repo, which runs the publish scrubber first. No telemetry, no SaaS. The opportunistic npm update check is the one network call, and it never runs in CI or when THREADNOTE_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER is set. See Safety and Security.

Which agents are supported?

Codex (CLI), Claude Code, Cursor, and GitHub Copilot (VS Code). Install the MCP adapter for each agent you use; threadnote install upserts user-level instruction guidance for all four. See Installation and Agent Instructions.

What happens when the context window compacts?

The durable feature memory and the latest handoff are recalled on the next turn, instead of relying on the compressed conversation summary alone. On Claude Code, the PreCompact hook snapshots a handoff first, so even a manually missed handoff survives compaction.

Do I run threadnote commands myself?

Normally no. You talk to your agent the way you already do; the agent calls the MCP layer (recall_context, remember_context, and so on) and the memory stays in sync across sessions, agents, and teammates. The threadnote CLI is the fallback path for when MCP tools are unavailable. See CLI Reference.

What if I switch agents mid-task?

Store a handoff before you pause, then open the next agent — it recalls the same handoff and durable memory and picks up the test command and open blocker without you retyping them. Because URIs and the project/topic path are stable, the next agent reads the same pointers.

threadnote handoff --project my-repo --topic feature-x --task "..." --tests "..." --next-step "..."

Is my data encrypted at rest?

Not by threadnote. Storage is plain Markdown on disk under THREADNOTE_HOME/data/viking/<account>/..., with a regenerable LevelDB vector index alongside it; the Markdown on disk is the source of truth. Encryption at rest is a rollout requirement you configure outside threadnote. See Safety and Security.

What you say -> what the agent does

Three representative flows. You speak naturally; the agent translates to MCP calls.

You: "Continue where we left off on this branch."
Agent: recall_context({"query":"<branch> latest handoff durable feature memory",
                       "callerCwd":"/abs/workspace/path"})
       -> reads the active handoff + durable feature memory, resumes without re-explaining.

You: "Save where we are — I'm switching to another agent."
Agent: remember_context({"kind":"handoff","project":"<repo>","topic":"<feature>","text":"..."})
       -> next agent's recall (and Claude SessionStart hook) picks it up.

You: "Share this feature's design memory with the team."
Agent: share_publish({"uri":"viking://user/you/memories/durable/projects/<repo>/<feature>.md"})
       -> scrubbed, pushed to the team repo; teammates' next recall auto-syncs it.

See also: Memory Lifecycle, Recall and Read, Sharing Memories, Safety and Security, Architecture.