Shared local context
for development agents.

One memory layer Codex, Claude, Cursor, and Copilot all see. Durable feature knowledge, recent handoffs, and team-shared decisions — recallable from any session, on any agent, in any worktree.

Agent context is ephemeral. You aren't.

Every new session your agent starts from zero. You re-explain the same architecture, repaste the same handoff, and rediscover the same gotchas. Across four different agents this multiplies.

• Conversation history evaporates. Compaction summarizes; the nuance is lost.
• Each agent has its own memory. Switching from Codex to Claude means starting over.
• CLAUDE.md/AGENTS.md is per-repo and static. It can't 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 you only remember to write them half the time.
• Team knowledge stays in DMs. Decisions made in Slack thread #1842 don't reach your teammate's agent.

A safe local memory layer for the agents you already use.

Threadnote sits between your agents and a local OpenViking store. One stdio MCP adapter, one URI scheme, one set of commands. Everything stays on your machine until you explicitly publish it.

Use them. Threadnote is not a replacement.

They are perfect for stable, canonical, version-controlled rules. They are wrong for living context — what happened in the last session, which branch is mid-refactor, which on-call workaround actually shipped.

The split: put repo policy in the .md files. Put feature history, in-flight task state, handoffs, and personal workflow facts in threadnote.

One MCP adapter, one URI scheme, one local store.

Local by default. Explicit when it isn't.

Threadnote is designed for an environment where agents write to your memory. The defaults assume that's untrusted and that mistakes happen.

One command. Then point your agents at it.

The installer wires up the npm package, the OpenViking Python environment, and the local server. After that, mcp-install per agent and you're done.

$ curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh

Installed threadnote@0.4.1
Already exists: ~/.local/bin/threadnote
OpenViking installs into Python; neither uv nor pipx is
on PATH so threadnote would fall back to `pip install
--user`, which fails on PEP 668 setups.
Install uv now? [Y/n] Y
Installing uv via Homebrew…
OK   openviking 0.3.12 ready · server healthy

$ threadnote mcp-install codex --apply
$ threadnote mcp-install claude --apply
$ threadnote mcp-install cursor --apply
$ threadnote mcp-install copilot --apply
Installed MCP server `threadnote` for codex, claude,
cursor, copilot. Restart agent sessions to pick up.

$ threadnote doctor --dry-run
Summary: 0 failure(s), 0 warning(s)

Open a fresh agent session after installing MCP — the tool list reloads at session start.

Pull just the curated docs into recall.

Threadnote does not index whole repos. Instead, point it at a seed manifest of paths you actually want agents to recall — typically AGENTS.md, CLAUDE.md, repo docs, and SKILL.md guidance.

$ threadnote init-manifest \
    --repo ~/src/web-app \
    --repo ~/src/mobile-app
Wrote ~/.openviking/seed-manifest.yaml (2 project(s))

$ threadnote seed
Imported 47 curated path(s); skipped 6 secret-flagged.

$ threadnote seed-skills
Imported SKILL.md catalog from Codex, Claude, repos.

version: 1
projects:
  - name: web-app
    path: ~/src/web-app
    uri: viking://resources/repos/web-app
    seed:
      - AGENTS.md
      - CLAUDE.md
      - docs/**/*.md
      - .claude/skills/**/SKILL.md
  - name: mobile-app
    path: ~/src/mobile-app
    uri: viking://resources/repos/mobile-app
    seed:
      - AGENTS.md
      - docs/**/*.md

• Recall is smart enough to scope by query. Ask "web-app durable feature memories" and recall prefers viking://resources/repos/web-app first.
• Seeding is opt-in and re-runnable. threadnote seed never deletes; it upserts.
• Skills are a first-class catalog. seed-skills makes reusable workflows discoverable: testing, release, on-call, debugging, plugin guidance.

Always one command from a clean state.

$ threadnote update
Latest: threadnote@0.4.1 (installed: 0.4.0)
Running: npm install -g threadnote@0.4.1
Running: threadnote repair
All checks passed. Restart agents to reload MCP.

$ threadnote repair
OK   threadnote shim: ~/.local/bin/threadnote
OK   codex / claude / cursor / copilot user instructions
OK   manifest, ignore file, templates
OK   openviking health
Summary: 0 failure(s), 0 warning(s)

Durable. Handoff. Archived.

Three lifecycle states, one stable URI per project/topic. Updates replace, never accrete.

# Capture an in-flight feature memory and its current handoff side by side:
threadnote remember \
  --kind durable --project web-app --topic auth-token-refresh \
  --text "Architecture: provider-only token client, JWT helpers in jwt.ts..."

threadnote handoff \
  --project web-app --topic auth-token-refresh \
  --task "Address reviewer comments on token refresh PR" \
  --tests "make lint-lite; mocha auth_client_test 77 passing" \
  --next-step "Push and request re-review"

# Later, update the durable memory in place (no timestamped duplicates):
threadnote remember \
  --kind durable --project web-app --topic auth-token-refresh \
  --replace viking://user/<you>/memories/durable/projects/web-app/auth-token-refresh.md \
  --text "..."

Curated memories. Yours to push. Theirs to pull.

threadnote share publishes a subset of durable memories into a git repo so other engineers' agents can recall them. Personal handoffs, preferences, and unpublished durables always stay local.

$ threadnote share init git@github.com:org/team-memories.git
Cloned into ~/.openviking/data/.../memories/shared/default/
Ingested 12 shared memory file(s) into OpenViking.
Added .gitignore exclusions for OV directory summaries.

$ threadnote share publish \
    viking://user/<you>/memories/durable/projects/<p>/<t>.md
Scrubber: no secret patterns detected.
git commit -m 'share: publish durable/projects/<p>/<t>.md'
Published. Pushed to origin/main.

$ threadnote share sync
git pull --rebase
Reindexed 3 file change(s) into OpenViking.
Recall now finds new shared memories alongside personal.

$ threadnote share unpublish <shared-uri>
Wrote back to personal namespace.
git rm + commit + push.

• Only durable/ memories are shareable. Handoffs, preferences, incidents, and everything else stays local by construction.
• Concurrent-publish safe. If two teammates publish the same project/topic at the same time, the retry path won't silently overwrite the other's write.
• MCP-native too. Agents can call the share_publish tool directly when they decide a memory is teammate-worthy.

What you say. What the agent does.

You don't run threadnote commands yourself. You talk to your agent the way you already do; the agent calls the MCP layer and the memory stays in sync across sessions, agents, and teammates.

recall_context({query: "<branch> latest handoff durable feature memory"})

→ viking://user/you/memories/handoffs/active/<branch>/auto-precompact.md
→ viking://user/you/memories/durable/projects/<repo>/<feature>.md

remember_context({kind: "handoff", project: "<repo>", topic: "<feature>", text: "..."})

Stored: viking://user/you/memories/handoffs/active/<repo>/<feature>.md

share_publish({uri: "viking://user/you/memories/durable/projects/<repo>/<feature>.md"})

Published → shared/<team>/durable/projects/<repo>/<feature>.md
git push: ok

remember_context({kind: "handoff", project: "<repo>", topic: "auto-precompact", text: "..."})

Stored: viking://user/you/memories/handoffs/active/<repo>/auto-precompact.md

remember_context({kind: "durable", project: "<repo>", topic: "release-process", text: "..."})

Stored: viking://user/you/memories/durable/projects/<repo>/release-process.md

recall_context({query: "export workflow timeout findings"})

→ viking://user/you/memories/durable/projects/<repo>/export-timeout.md (score 0.71)

Try it on your machine in 90 seconds.

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

threadnote · MIT · built on OpenViking 0.3.12 · use ↑ ↓ / j k to navigate