thr

thr is a small local CLI for saving explicit memories and recalling them later by meaning or text. It is built for agent workflows: stable JSON output, offline semantic search, and installable skills for Codex, OpenCode, and Claude Code.

Install

curl -fsSL https://raw.githubusercontent.com/Chadi00/thr/master/install.sh | bash

The installer downloads the latest macOS or Linux release, verifies signed checksums, and installs the binary. If the selected default database (THR_DB or ~/.thr/thr.db) exists, it also runs its backed-up migration. Recognized managed agent skills are updated automatically; the optional prompt is only for a new skill. Prefer manual verification? See MANUAL_INSTALL.md.

Quick Start

thr add "This project prefers small PRs with tests"
thr ask "how should I structure this PR?"
thr search "small PRs"
thr list

thr ask performs semantic recall over your saved memories. It does not call an LLM or generate an answer.

Agents

Install the thr skill for your coding agent:

thr setup codex
thr setup opencode
thr setup claude-code

After that, an agent can retrieve durable facts with thr --format json-v2 ask or search, then maintain memories with add, edit, move, and forget.

Scopes

Inside a Git repository, default recall searches that repository plus the user scope, while an unqualified write uses the repository scope. Broad writes are explicit:

thr add "This repository uses pnpm"
thr add --scope user "The user prefers concise explanations"

Outside a repository, default recall searches user and writes require --scope user. Use --scope repo for only the current repository, --scope repo:<id> for another registered repository, or repeated --scope/--all-scopes for explicit unions. --cwd /path/to/repo changes repository context without changing the shell directory.

thr --format json-v2 context
thr --cwd ../other-repo --format json-v2 ask "release process"
thr --format json-v2 scope list
thr move 42 --to repo:<id>

JSON v2 reports the selected database, searched scopes, result scopes, warnings, and structured errors. Existing --json output remains available as the legacy format.

Features

• Local first: memories live in your own SQLite database.
• Semantic and text recall: use ask for meaning, search for exact or fuzzy text.
• Agent ready: JSON output and packaged skills make it easy for agents to use safely.
• Offline by default: the embedding model and ONNX Runtime are bundled with the release.
• Explicit memory: thr stores only what you save.

CLI

thr add <text>          Save a memory
thr add -               Save stdin
thr list                List memories and ids
thr show <id>           Print one memory
thr ask <question>      Retrieve semantically similar memories
thr search <query>      Search memories by text
thr edit <id> <text>    Replace a memory
thr forget <id>         Delete a memory
thr move <id> --to ...  Move a memory between scopes
thr stats               Show database path and count
thr index               Rebuild semantic embeddings
thr context             Inspect repository and scope context
thr scope ...           Inspect or manage scopes
thr migrate             Explicitly run a backed-up migration
thr prefetch            Prepare the model cache
thr setup <agent>       Install an agent skill

Useful flags:

thr --db ./thr.db ...
THR_DB=./thr.db thr list
thr --format json-v2 ask "repo conventions"
thr search -n 5 "release notes"

Data

Memories are stored as local plaintext SQLite. The default data directories are created with private filesystem permissions, but the database is not encrypted at rest.

The installer migrates its selected default database automatically. Other legacy databases, including custom --db paths, migrate on first operational access after a private verified backup is created. thr context is the read-only exception: it reports migration_required without changing the database. You can run thr --db <path> migrate explicitly at any time.

Legacy memories are assigned to user with scope_assignment: legacy_default so existing visibility is preserved until reviewed and moved. A scoped database cannot be opened by older binaries; downgrade by restoring the reported pre-migration backup.

thr has no telemetry. Release archives include the embedding model and runtime needed for offline semantic search.

Platform

Prebuilt releases support macOS arm64/x86_64 and glibc Linux arm64/x86_64.

Windows and Alpine/musl Linux are not supported yet.

Links

• Releases
• Changelog
• License
• Third-party notices