v0.9.0 — the handoff skill

Tars now ships agent skills next to its routines, in skills/. A routine is a prompt you hand to a scheduled task; a skill is Markdown the agent loads on its own when the work matches it.

handoff

The first one covers both sides of a context boundary — a new session, a /clear, a fresh worktree, a subagent returning to its coordinator, a different model, or a human picking up where an agent stopped.

• Writing. Eight sections — Objective, State, Verify-before-you-build, Decisions, Rejected, Open questions, Next action, Pointers — and you delete the empty ones instead of writing "N/A". Two conventions carry most of the value: mark provenance inline ((verified: pnpm test, 14:20) vs (assumed)), and hand over a verification command rather than a status claim, because an agent grading its own output is the weakest signal in the document.
• Reading. A received handoff is a claim from a prior session, not ground truth. Orient, run the verify step, reconcile against live state — live state wins — and only then start new work.
• The one rule. Carry what cannot be re-derived; point at everything else. Why a decision went the way it did, the dead ends and why they died, constraints stated only in conversation, environment quirks learned the hard way. Anything sitting in git, the test suite, or a PR gets a pointer.

It also drops the habits that stopped helping: CRITICAL:/YOU MUST padding, prescribed ten-step scripts, example walls, and the inherited "context is nearly full, wrap up fast" panic — all of which make a Claude 5 receiver worse, not more careful.

Why it belongs in a memory repo

The brain and a handoff split the same problem. The graph holds what stays true; the handoff holds what is only true right now — the half-finished migration, the command that proves it, the dead end not to re-run. So the skill writes durable facts into the brain via the memory_* tools and keeps the artifact itself disposable, which is the repo's "brain over Markdown" rule rather than an exception to it.

Install

cp -r skills/handoff ~/.claude/skills/

No code, no dependencies — Markdown with name and description frontmatter. Other hosts: point yours at skills/handoff/SKILL.md.

v0.8.0 — Open source: one-command install, LOCOMO benchmark, MIT

Install it in one command

The setup driver is agent-first — hand it to Claude Code and it stands Tars up itself:

curl -fsSL https://raw.githubusercontent.com/fonsecabc/tars/main/install.sh | bash

install.sh is dependency-free and idempotent: it clones (or updates) the repo and hands off
to tars init, which provisions any of four components — the engine, an always-on
service, the Claude Code MCP registration, and a personalized persona — then prints a
JSON summary an agent reads to continue. Run it headless with
--all --owner-name "Ada" --install-prompt --yes --json.

Also new: a bin/tars CLI, a Dockerfile, and deploy/docker/docker-compose.full.yml for a
one-command Postgres + server stack.

Benchmarked on LOCOMO

Retrieval now has numbers instead of vibes. packages/core/src/eval/locomo/ ingests all ten
LOCOMO conversations as verbatim, timestamped observations and answers strictly from what
memory_recall returns.

• Retrieval hit-rate 82.9% over the 1,540 answerable questions (81.3% across all 1,986,
  including the 446 adversarial ones where abstaining is the correct behavior).
• Answer accuracy 48.4% → 54.6%, temporal questions 4% → 27.1%, adversarial abstention
  90.4% → 92.4%.
• The temporal jump was a rendering fix, not a retrieval one. Every observation already
  carried an absolute validFrom; it just wasn't surfaced. Prefixing each recalled line with
  its bracketed date was the entire change.

The harness runs fully local (qwen2.5:14b answers, 32b judges, nomic-embed-text embeds),
so answer accuracy is capped by a small model — the hit-rate is the model-independent
number, and these figures are for comparing Tars configurations against each other, not against
leaderboard scores judged by frontier models. Reproduce with
packages/core/src/eval/locomo/download.sh.

Chronicle — one shared session log

Every harness — Claude Code sessions, cron routines, the voice loop — now writes to a single
loopback session log, so they can see and message one another.

• Transactional store + ops layers over a new sessions migration, lane-gated.
• Harness adapters: Claude Code shadow tailer, cron recorder, voice capture.
• Inter-session message and signal lanes with per-session inboxes.
• /watch — a live dashboard served on the loopback listener.

Loopback-only by design. Don't expose it.

The voice stack is public

The always-on voice loop (mic → whisper → router → speak) now ships owner-configurable, with
personal paths and data scrubbed out.

MIT

Relicensed to MIT.

Also

• com.tars.janitor process-hygiene agent, plus a cloud deploy scaffold (deploy/cloud/) with
  restic backups.
• Hermetic tests for the embedding providers, rerank client, and env config; coverage reporting
  and a .gitleaks.toml.

115 files changed, +13,135 / −364.

v0.7.0 — Adaptive onboarding + AI context import

Adaptive onboarding — right-sized to the person and their Mac

make setup now assesses your Mac (RAM/chip) and asks one plain-language question:

• Simple (default) — smart brain + memory graph. No local AI model, no Ollama, nothing extra to keep running. Best for laptops and non-technical users.
• Full — also installs local embeddings + the voice stack (wants 16GB+ RAM, an always-on Mac).

Set TARS_PROFILE=simple|full to run unattended. Fixes the old bug where setup hard-coded EMBEDDING_PROVIDER=ollama while .env.example claimed null.

Two easy ways to seed the brain

• Conversational interview (docs/routines/interview.md) — TARS asks one plain question at a time and remembers your answers. No forms, no connectors, ~10 min.
• Import from another AI (docs/routines/context-import.md) — a portable prompt for ChatGPT / Gemini / any assistant to export a profile of you (identity, people, work, voice & humor, and the tools you use). TARS ingests it to tune its persona dials to how you actually talk and to suggest which connectors to set up.

Also

• Bootstrap scrape now spans the computer (macOS MCP — Notes, Contacts, files) and connectors.
• docs/onboarding.md rewritten non-tech-first; voice / tunnel / hosted-embeddings moved to power-user extras.

v0.6.0 — Dream Stage 5: nightly context primer

Dream Stage 5: nightly context primer

Dream now closes each night by writing a short, self-overwriting "what's
still open" note into the host's persistent instructions file (e.g. Claude
Code's global CLAUDE.md), so a brand-new session starts oriented instead
of cold — it already has a glance at active threads and open commitments
before it ever calls memory_recall.

• New Stage 5 — "Prime": gathers tonight's consolidated entities plus
  any still-open commitment/plan/blocked observations (any age,
  unresolved), drafts at most 8 one-line bullets, and writes them into a
  guarded <!-- TARS:TODAY:START/END --> block. Full overwrite every
  night, never appended — resolved items just drop off.
• One narrow, deliberate exception to "brain over Markdown": this
  block is a disposable cache regenerated nightly purely to seed a fresh
  session's context — the brain remains the sole source of truth. Only
  the marked block is ever touched; nothing else in that file.
• Degrades quietly: skips the stage (never fails the run) if the
  target file is missing or unwritable.
• Generalized in the host-agnostic docs/routines/dream.md
  as an optional PRIMER_TARGET, for hosts that keep instructions in a
  file at all (skipped where instructions live in a UI field instead).

Docs-only release — no code or schema changes.

v0.5.0 — X/Twitter integration

X/Twitter integration

Adds X/Twitter as a source alongside WhatsApp/LinkedIn — mentions, DMs, posting,
and replying — via X's own official CLI/OAuth2 MCP bridge (xurl),
not a cookie/session-scraping library. Every unofficial alternative surveyed
carries real, maintainer-acknowledged account-ban risk, which isn't a trade
worth making on a real personal account.

• New: x MCP entry in .mcp.json.example (npx launcher,
  no local build required).
• New: docs/mcps.md setup section — Pay-per-use enrollment,
  the "Read and write and Direct Messages" app-permission gotcha (the default
  tier silently blocks DM scopes), OAuth2 callback config, and the credits
  requirement (auth can succeed while calls still 402 until the app is funded).
• X/Twitter wired in as a social source in both the
  briefing and dream
  routines' SOURCES config, same agnostic pattern as every other connector —
  no hardcoded account, so any Tars instance can plug in its own.
• Known limit: official DM reads are capped at 15 requests/15min,
  user-context OAuth only — no bulk/app-only tier. Routines should poll with
  that ceiling in mind.

Docs/config-only release — no code or schema changes.

v0.4.0 — Voice personas

Voice personas

Adds a documented pattern for learning how the user writes on each messaging
platform (Slack, email, WhatsApp, LinkedIn, Twitter/X) and drafting future
messages in that same voice.

• New: docs/routines/voice-personas.md
  — a routine that samples the user's own sent messages per platform, stores
  the derived style as a voice_persona brain entity (tone, structure,
  punctuation/emoji habits, openers/closers, vocabulary, audience-tagged
  register variants), and recalls it before drafting anything on that
  platform. Drafting always previews before send — never auto-sends.
• Generalizes the ad-hoc taste-slack-voice / whatsapp-voice skills: the
  brain becomes the source of truth for the voice itself, re-derivable and
  correctable rather than hand-maintained prose.
• README and docs/mcps.md now point to the new routine.

Docs-only release — no code or schema changes.

v0.3.0 — Self-resolving bootstrap identity

The one-time Bootstrap routine (added in v0.2.0) no longer needs the operator to hand-type the owner's name into the Configuration block. Its Seed phase now resolves identity automatically — from Claude Code's local git config or an already-injected account identity — and only asks directly when that's ambiguous or missing.

v0.2.0 — Clone-and-go onboarding

Clone-and-go onboarding

Ties together Tars's existing setup automation, MCP companion docs, persona
prompt, and routines into one ordered Day-0 runbook — a fresh clone can now be
taken end to end (server → MCPs → persona → seeded brain → scheduled routines)
without tribal knowledge.

• New: docs/onboarding.md — the Day-0 runbook.
• New: docs/routines/bootstrap.md — a
  one-time, wide-window sweep across every connected source that seeds the
  brain before Dream/Briefing (which only reconcile new activity) have
  anything to work with.
• Dream and Briefing routine docs now include concrete "Instantiating on
  Claude Code" steps (the /schedule skill + a personal drop-in file
  pattern), replacing the previous "copy this into a scheduled task."
• docs/tars-system-prompt.md now specifies the persona goes in the global
  ~/.claude/CLAUDE.md, not the project one.
• README and CLAUDE.md point new users/sessions at the runbook.

Docs-only release — no code or schema changes.

v0.1.0 — Small-model recall + benchmark-driven retrieval

First tagged release. Focus: make recall fit small / local models, and put retrieval quality under continuous measurement.

Highlights

• Compact recall output — memory_recall gains format:'compact' + maxChars: terse, id-free text with relations rendered by name, bounded to a hard character budget. JSON stays the default, so tool-using clients are unaffected.
• Retrieval quality overhaul — weighted Reciprocal Rank Fusion, own-relevance-gated graph spreading activation, an exact name/alias match bonus, and an optional local-LLM reranker (RERANK_ENABLED). Every change is gated by an option, so the prior behaviour is exactly recoverable.
• RAG benchmark (packages/core/src/eval/) — a synthetic, privacy-safe brain + 40 gold queries across 9 query kinds + standard IR metrics (Recall@k / MRR / nDCG), runnable against local Ollama, with a hermetic CI regression guard.
• Env-configurable recall defaults (TARS_RECALL_*).

Benchmark results

Measured on the bundled synthetic benchmark (40 queries over a 26-entity abstract graph; local Ollama nomic-embed-text embeddings). Headline = a top-heavy nDCG@3 composite, which models what a small model with a tight context budget actually reads.

Full pipeline vs the original retriever

	Composite	hit@1
Original retriever	0.737	0.65
Improved pipeline	0.964	0.93
Δ	+22.7 pp	+28 pp

Isolating the LLM reranker (retrieval tuning held constant)

Query kind	Without reranker	With reranker
exact	1.00	1.00
alias	1.00	0.89
semantic	0.71	0.99
attribute	0.85	1.00
multi-hop	0.64	0.94
two-hop	0.66	0.88
collision	0.28	1.00
negative	0.89	1.00
temporal	1.00	1.00
overall	0.743	0.964

Reranker delta: +22.1 pp (0.743 → 0.964, reproducible at temperature 0). The reranker is what cracks relational ("who does X's manager report to") and name-collision ("the Alex who works at Acme") queries that pure lexical/vector/graph ranking cannot.

Enabling

• Compact output: pass format:'compact' per call, or set TARS_RECALL_FORMAT=compact.
• Reranker: RERANK_ENABLED=1 (optional OLLAMA_RERANK_MODEL, default qwen2.5:14b-instruct). Off by default — it adds one local LLM call per recall, worth it on the small-model serving path.

Notes

• The numbers come from a synthetic benchmark and measure the query shapes it covers; re-measure against real data as a brain grows.
• Retrieval runs fully local (Ollama); no data leaves the machine.

🤖 Generated with Claude Code