Tether

tether

A shared memory layer for personal agents, across devices. tether is an MCP server backed by a local SQLite file. Any MCP-compatible agent can remember, recall, link, and forget durable notes — facts about you, your projects, your preferences — so context follows you instead of dying with each session.

It runs local-only with zero configuration. Point it at a hosted libSQL/Turso primary and the same file becomes an embedded replica that syncs your memory across every device in near-real-time.

Why

The near future is personal agents living across many devices — laptop, desktop, phone. For that to feel like *one* assistant rather than several amnesiac ones, memory has to be a substrate that follows you: readable and writable from every device and from any agent, not siloed inside a single tool.

tether is that substrate. It is deliberately a *convenience layer* — it makes an agent more useful when present, and never breaks the agent's work when degraded.

Status

v0.6.1. The core (four memory verbs + boot index + FTS5) shipped in v0.1; since then recall has grown a semantic arm, consolidation, an associative usage graph, a self-organizing store, and opt-in crystallization — each additive and each degrading cleanly to plain keyword recall. Every feature below is implemented.

Design and rationale start at docs/superpowers/specs/2026-07-03-tether-design.md; the associative core, seed-dominant recall, self-organizing store (Tier B1), and crystallization (Tier B2) each have their own design doc under docs/superpowers/specs/, with matching plans in docs/superpowers/plans/.

Design at a glance

• Four memory verbs: remember · recall · link · forget. (Enabling crystallization adds one reflection-control tool, dismiss_cluster — not a memory operation.)
• Upsert on write so the store doesn't rot into near-duplicates.
• Rich recall (id, type, title, body, tags, updated_at, plus a via receipt saying why each hit surfaced) so an agent can judge staleness and cite what it updates. body is a query-centered excerpt, not the whole memory — see Excerpts.
• An auto-loaded boot index — a compact one-line-per-memory list surfaced to the agent each session, so memory helps even when the agent doesn't think to search.
• Local-first, sync optional — the local path is untouched when no backend is configured; degradation never throws.
• Hybrid search, associative on top — FTS5 keyword hits and local static embeddings are fused, then a usage graph (explicit links, learned co-recall, semantic neighbours) pulls in connected memories. Every layer is additive and degrades to plain keyword recall.
• Safe under parallel tool calls — an agent that fires several remember/recall calls at once gets atomic, correctly-reported results; see Performance and durability.

Install

Requires Python ≥3.10 on Linux, macOS, or Windows.

Register it with Claude Code — with uv:

claude mcp add tether -- uvx tether-memory

…or install it first:

pip install tether-memory

claude mcp add tether -- tether-memory

(The package is named tether-memory on PyPI — tether was already reserved as a common brand name. tether in claude mcp add tether -- ... is just the label Claude Code uses to refer to this server; it doesn't need to match the installed command.)

Or add it as a Claude Code plugin (this repo doubles as a one-plugin marketplace; the plugin runs uvx --from 'tether-memory[semantic]', so semantic recall comes along):

/plugin marketplace add sidyellur/tether

/plugin install tether@tether

It is also listed in the MCP Registry as mcp-name: io.github.sidyellur/tether.

By default memory lives in a local SQLite file at ~/.local/share/tether/memory.db — on Windows, %LOCALAPPDATA%\tether\memory.db (override either with TETHER_DB, or set XDG_DATA_HOME, which is honored on every platform). No accounts, no network — this is the whole tool for a single machine.

Project awareness

tether knows which project it is serving: Claude Code sets CLAUDE_PROJECT_DIR in every MCP server's environment, and tether takes the directory's name as the project (override or disable with TETHER_PROJECT). That drives three things, none of which need configuration:

• The boot index leads with this project. The auto-loaded index opens with a # This project ( ) section, then # Everything else, so the agent starts a session already looking at the decisions and gotchas for the repo it is in rather than whatever you touched last, anywhere.
• Work memories are tagged automatically. project, feedback and reference memories get a proj: tag unless the agent passes a proj: tag itself. user memories are about you, not the work, and stay global. The tag is an ordinary tag: recall(tags="proj: ") lists a project's memories deterministically.
• Recall prefers this project on a near-tie. A hit tagged with the current project ranks a few places ahead of an equally-good hit from another project; it never outranks a clearly better match, and untagged memories are neither boosted nor penalized.

Nothing falls back to the working directory: outside Claude Code (or with TETHER_PROJECT=off) tether behaves exactly as before.

Sync across devices (optional)

Point tether at a Turso / libSQL database and the local file becomes an embedded replica — local-speed reads, writes that propagate to your other devices. Install the extra and set two env vars:

pip install 'tether-memory[sync]'

export TETHER_SYNC_URL='libsql:// .turso.io' export TETHER_SYNC_TOKEN=' '

If the backend is unreachable, tether logs sync offline and keeps working against the local file. Sync is a single-primary design: every write goes to the hosted primary and replicas only pull, so a device that was merely offline catches up (including tombstones from forget) on its next pull and can never resurrect a memory another device forgot. The one gap: writes made *while degraded* land only in that device's local file and are not merged back later (#99 tracks reconciliation).

Writes push immediately. Reads also pull, debounced to at most once every TETHER_SYNC_READ_INTERVAL seconds (default 30) — so a device that only *asks* things still sees what your other devices wrote, instead of staying frozen at its own startup state until it happens to write something. The read-path pull is bounded much more tightly than the write-path one: if the backend is slow, the recall returns local data and the pull lands for the next read rather than making you wait.

One thing to know about replicas: libSQL forwards every write to the hosted primary, and with the associative graph on (the default) recall writes too — it records what was recalled together so memories can wire up over time. On a replica that makes each recall a few network round-trips on top of the local search. If that matters more to you than learned associations, TETHER_ASSOC=0 makes recall read-only again.

Keyword search

The keyword arm is SQLite FTS5 over title, body and tags, ranked by bm25. Ask in plain language: a memory that contains *some* of the query's words is a hit, and one that contains more of them ranks higher, so "how do we run the integration tests?" finds the note that says "pytest runs the tests" (common function words are ignored). The index stems English words, so tests matches test and deciding matches decided. Stemming is English-only; turn it off for a store in another language and tether rebuilds the index on the next start.

Measured on the LoCoMo long-conversation benchmark (one memory per dialogue turn, 1,536 questions, "did recall return the turns that answer it" in the top 10), the keyword arm alone finds the evidence for 61% of questions, against 54% for a textbook BM25 over the same text. That harness ships in the repo — see Benchmarks.

Semantic search (optional)

By default recall is hybrid: keyword (FTS5) results are fused with semantic (vector) results, so a query finds relevant memories even when the exact words differ ("automobile" recalls a note about your "car"). Semantic recall runs a small static embedding model locally — no network, no API key, nothing to hang on. Install the extra:

pip install 'tether-memory[semantic]'

Without the extra (or with TETHER_SEMANTIC=0), tether runs keyword-only FTS5 — semantic is a pure add-on and never a requirement. The first run embeds existing memories once (a one-time backfill); after that it is incremental.

Environment:

Consolidation (optional)

tether keeps a superseded fact rather than overwriting it: when a memory is replaced, the old one is marked no longer current (retained for history) and excluded from recall and the boot index. Recall also gently favors more recent facts. Two opt-in behaviors go further:

Consolidation never deletes — forget soft-deletes (see Tools), and only the admin CLI's purge is permanent. All of this degrades to plain keyword recall when the semantic extra is absent.

Associative recall (optional)

recall doesn't just return keyword/semantic matches — it follows a usage graph to related memories, so asking about one thing surfaces its connected context. The graph's edges come from three local, deterministic sources — no LLM, no network:

• semantic — nearest neighbours by embedding (needs the [semantic] extra),
• explicit — the link() verb,
• hebbian — memories you recall *together* get wired together over time.

Every hit carries a via receipt saying why it surfaced (a direct match, or the edge it came through), and two optional recall args tune it:

| TETHER_SEED_FLOOR | 0.35 | minimum cosine similarity a semantic hit needs to seed an associative wa