Skip to content

Home

Jump to bottom
Denys Kashkovskyi edited this page Jul 23, 2026 · 7 revisions

Home

Threadnote lets one engineer's coding agent publish a durable project decision that another engineer's different agent can recall. Alice can capture an API contract with Codex; Bob can auto-sync and read it from Claude Code, Cursor, or Copilot during the next task.

That cross-user, cross-agent path is the product's main value. Persistent personal memory is the foundation, not the destination.

Alice + Codex ──publish curated memory──▶ team Git repo
                                              │
                                      auto-sync on recall
                                              ▼
                              Bob + Claude Code / Cursor / Copilot

Personal handoffs, preferences, incidents, and unpublished memories stay local. Only curated durable knowledge or reusable artifacts that a user explicitly publishes enter the team Git repo, after preview and secret scanning.

What breaks without it

  • Useful discoveries stay trapped in one person's chat or one vendor's project.
  • Each coding agent has its own context. Switching users or vendors means starting over.
  • Persistence alone creates better private silos; it does not make project knowledge portable to a teammate's agent.
  • 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.
  • Team knowledge stays in DMs. A decision made in a Slack thread never reaches a teammate's agent.

Different from native AI memory

ChatGPT, Gemini, and Claude provide useful continuity inside their own products. ChatGPT and Claude support shared projects; Gemini can share Gems and chats. Threadnote solves a different boundary: a team can keep explicit engineering knowledge in Markdown and Git, then let each developer use it from a supported coding agent without standardizing on one AI vendor.

Threadnote Native memory / vendor collaboration spaces
Reach Across users, machines, and supported coding-agent vendors Inside the provider's account, app, shared project, or Gem
Team source of truth User-controlled Markdown and Git Provider-hosted chats, files, memory, and settings
Knowledge unit Explicit durable/handoff/archive record with a stable URI Provider-managed memory, project, Gem, or conversation
Recall path Local semantic index returns URI candidates; agents read selected records Provider-managed retrieval and search
Sharing boundary Publish selected durable knowledge; personal working state local Membership, links, and controls within the provider
Best fit Engineering teams using multiple agents in real repositories Continuity and collaboration inside one AI product

See Threadnote vs Native AI Memory for a product-by-product comparison and links to the official documentation.

What you get

  • One engineer's learning reaches every teammate's agent. Shared memories auto-sync before normal recall/read calls.
  • The team does not have to choose one agent vendor. Codex, Claude Code, Cursor, and Copilot use one MCP workflow.
  • Sharing is explicit and reviewable. Preview, scrub, commit, and push only selected durable memories or artifacts.
  • Private working state stays private. Personal handoffs and unpublished context remain on the local machine.
  • Recall is local and context-efficient. A local embedding model ranks semantic matches, then the agent reads only the selected viking:// records instead of replaying the full memory history.
  • 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.
  • Cross-repo work stops scattering context. Worksets let you recall related repos together, such as a mobile app, web app, and shared library.
  • Handoffs can carry review state. PR, issue, CI, blockers, next steps, and referenced memories stay attached to the current work log.
  • 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. By default, OpenViking builds the semantic index locally with a GGUF embedding model through llama.cpp, so the memory corpus does not need to be sent to a hosted embedding service for recall.

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."

Cross-repo work with threadnote: "I recall the mobile_web workset once and see the relevant handoffs, seeded guidance, and dependency facts for both apps before changing either one."

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

The default MCP registration exposes six common tools; the CLI remains available for every advanced workflow. 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.
  • Threadnote vs Native AI Memory — why portable team memory is different from ChatGPT, Gemini, and Claude memory.
  • 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, worksets, dependency facts, 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