Skip to content

Home

Jump to bottom
Denys Kashkovskyi edited this page Jun 19, 2026 · 3 revisions

Home

threadnote is for engineers who are tired of re-explaining the same project context to every AI coding agent.

It gives Codex, Claude Code, Cursor, and Copilot one shared local memory for development work: durable decisions, current handoffs, seeded repo docs, reusable skills, and curated team knowledge. It is intentionally scoped to curated docs, memories, skills, and handoffs - it is not a source-navigation replacement, and it does not index whole repositories by default.

It is not a bigger prompt, and it is not just an auto-compacter. It is a workflow around Markdown-backed local memory: agents recall the relevant viking:// pointers, read only what they need, update one stable project/topic record, and leave your canonical repo docs alone.

Why it exists

  • Agent context is ephemeral. Every new session starts from zero, and compaction summarizes away the nuance.
  • Each agent has its own memory. Switching from Codex to Claude means starting over.
  • Markdown notes are passive. The agent still has to know which note matters now, whether it is stale, and where to write the next handoff.
  • CLAUDE.md / AGENTS.md is per-repo and static. It cannot carry an in-flight feature's design decisions across sessions, much less across agents or repos.
  • Hand-typed handoffs rot. The next session needs them, but they only get written half the time.
  • Team knowledge stays in DMs. A decision made in a Slack thread never reaches a teammate's agent.

What you get

  • Fresh agents start with recall, not amnesia. A new session can read the latest handoff before touching code.
  • Compaction becomes a checkpoint, not memory loss. Durable facts and current status survive the summary.
  • Agent switching stops resetting the task. Codex can leave a handoff that Claude Code, Cursor, or Copilot can read.
  • Repo docs stay clean. AGENTS.md, CLAUDE.md, and docs remain stable policy; threadnote carries living context.
  • Team context is explicit. Publish only curated durable memories to a team git repo; personal handoffs stay local.

Why not just Markdown files?

Use Markdown files. threadnote makes them operational.

  • AGENTS.md / CLAUDE.md / repo docs: stable, reviewed, version-controlled rules.
  • Random notes: easy to write, hard for agents to rank, scope, update, or know when stale.
  • threadnote memories: Markdown on disk plus semantic recall, stable URIs, lifecycle (durable, handoff, archived), scoped compaction, MCP tools, and safe team sharing.

The source of truth is still local files. The benefit is that agents know how to find the right file, decide whether it is current, update it without creating duplicates, and hand it to the next agent.

Agent perspective

These are workflow examples from an agent's point of view, not external endorsements.

Codex before threadnote: "I inspect the repo, ask what changed, rediscover the test command, and hope the compacted chat summary did not drop the important caveat."

Codex with threadnote: "I recall the branch handoff and durable feature memory first. I can name the files touched, the last failing check, the design decision behind the code, and the next step before editing."

Claude Code before threadnote: "A long debugging thread compacts into a vague narrative. The next turn knows the arc, but not the exact command, blocker, or decision."

Claude Code with threadnote: "The pre-compact handoff captures the concrete state. The next session reads the same memory and continues without asking the user to reconstruct it."

Quickstart

curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh
threadnote mcp-install claude --apply   # or codex / cursor / copilot
threadnote doctor --dry-run

Open a fresh agent session after installing MCP so the new server registration loads.

Explore the wiki

  • Installation — the one-line installer, manual install, runtime overrides, and updates.
  • Configuration — environment variables, THREADNOTE_HOME, host/port, and the seed manifest.
  • Architecture — how the stdio MCP adapter, openviking-server, the viking:// URI scheme, and on-disk storage fit together.
  • Memory Lifecycle — durable vs handoff, active vs archived, project/topic paths, and compaction.
  • Recall and Read — searching context, reading and listing viking:// URIs, and scope inference.
  • Seeding Repos and Skills — curated manifest seeding for repo guidance, docs, and SKILL.md catalogs.
  • Sharing Memories — publishing curated durable memories to a team git repo and syncing teammates' updates.
  • Safety and Security — local-by-default writes, ignore rules, redaction, secret scanning, and explicit config changes.
  • CLI Reference — every threadnote command and its flags.
  • Web Manager — the local web UI (threadnote manage) for browsing, editing, and managing memories.
  • Agent Instructions — the user-level guidance installed for Codex, Claude, Cursor, and Copilot, plus Claude Code hooks.
  • Migration — moving an existing repo workflow onto threadnote and migrating legacy memories.
  • Troubleshooting — diagnosing install, health, MCP, and server problems.
  • Concepts and FAQ — core terms and common questions.

Links

License: AGPL-3.0-or-later. Built on OpenViking 0.3.24. Requires Node.js >= 20.

See also: Installation, Architecture, Concepts and FAQ.

GitHub · npm · walkthrough deck · OpenViking · AGPL-3.0-or-later

threadnote

Start here

Concepts

Workflows

Reference

Clone this wiki locally