DESIGN.md@integrations/tau git:20260907.b7b8f39A

Immutable. This exact content is served forever at /api/v1/blob/13bbe37c5135fb0a.

# Basic Memory for Tau: continuity design

Issue: https://github.com/basicmachines-co/basic-memory/issues/1487
Integration: https://github.com/basicmachines-co/basic-memory/pull/1489
Required host work: https://github.com/huggingface/tau/pull/687

## Product contract

A fresh or compacted session recovers the objective, decisions, unfinished work,
verified findings, and next action through the shared Basic Memory graph. Full
MCP tool access supports that loop; it is not a substitute for it.

## Shared Basic Memory contract

`knowledge.py` models general/coding profiles at the configuration boundary and
collects Git/PR metadata into a small frozen value. The lifecycle selects an
explicit user-approved checkout profile; it does not discover write authority
from repository files. The general profile remains backward compatible with
existing `project` and capture controls. Coding profiles carry their own explicit
write project and read-only sources. Global lifecycle flags still govern both.

General snapshots use `session`; coding snapshots use `coding_session` with
required queryable Git identity. Canonical schemas live in
`integrations/shared/schemas`, with checked copies in each host package. Tau uses
the same schema categories and repository queries as the hook-backed integrations,
without importing the CLI or executing `bm hook`. Setup offers missing schemas
with consent; it does not overwrite user knowledge or customized definitions.

Repository identity, not cwd, scopes coding history across checkouts. Active tasks
and open decisions remain project knowledge; shared-project reads carry explicit
read-only labels. Broad coding-session topic/feed queries are excluded so another
repository's checkpoint cannot bypass the scope. Receipt recovery still uses
immutable source identity, independently of retrieval conventions.

Git metadata is required only for a new coding checkpoint; reconciliation never
needs current Git state. Optional GitHub PR lookup does not make local coding
require authentication. Subprocess cancellation retires the metadata reader before
returning. No detached writer, additional lifecycle telemetry store, or framework
of host adapters is introduced.

## Host dependencies, implemented separately

Stock Tau 0.4.1 only notifies extensions around overflow compaction. Its queued
custom messages run as follow-ups, which can cause an extra model response even
with trigger_turn=False. Its public context cannot read persisted custom receipts
or request a tool-free summary through the active provider.

Tau #687 supplies:

1. Awaited extension start/end notifications around manual, detailed manual,
   threshold and overflow compaction. No-op checks emit nothing. Failure and
   cancellation emit aborted end events. The original context remains available
   until start handlers finish.
2. `context.branch_entries`: deep-copied persisted active-path entries for receipt
   recovery and lineage without session-file scraping.
3. `context.summarize`: bounded tool-free active-model synthesis, no agent turn,
   history mutation, exposed credentials, or detached task.
4. `tau.append_message`: persist idle reference context before the next prompt,
   without queuing another turn.
5. Shutdown/start notifications around in-place tree branches on the same runtime.

The package pins the Basic Machines fork at `d8216af` until these interfaces are
released upstream. That revision deep-copies branch entries once at the session
boundary; the extension facade returns the isolated snapshot without recopying it.
It does not modify installed Tau or pretend #506 is fully closed: that issue's
threshold/manual frontend-iterator/TUI-status work is separate from extension
callback delivery. Persisted-entry notifications are not required; branch snapshots
provide authoritative receipt reconstruction.

## Explicit ownership

`bridge.py` finishes paginated discovery during synchronous setup using a joined
temporary thread/process, because Tau composes tools before session_start. The
probe closes before setup returns. Runtime MCP contexts belong to one async owner
task; calls share them. Close cancels active requests and retires contexts in their
owner task. Restart creates a fresh stop event, including same-runtime tree branches.

`extension.py` registers every advertised tool, preserving schemas and forwarding
arguments unchanged. `results.py` converts native text/images, preserves other
blocks and structured data, and validates write receipts. Routing and auth remain
BM's responsibility; automatic memory requires an explicit project destination.

## Knowledge and receipt flow

`continuity.py` reads public persisted message entries, excluding reasoning,
tools, synthetic summaries, and injected context. The last confirmed handoff plus
new public messages are synthesized in bounded chunks under one checkpoint deadline.
Knowledge capture at settled/compaction/shutdown uses the same source-tip identity;
unchanged state reuses its receipt instead of making redundant model requests.

Before a remote write, append a pending intent containing project, capture id,
kind, source tip, and content digest. After a validated BM result, append a confirmed
receipt with its returned path. Reload/start reconciles pending intents by reading
remote content, never resubmitting writes. A sibling branch can recover the same
source-tip capture by identity and byte digest. Divergent source tips produce
separate snapshots linked to the prior active-branch checkpoint. Transcript notes
are distinct, opt-in, immutable segments; handoffs link their captured sources.

Startup reads confirmed active-branch checkpoints before broader scoped results,
expands the checkpoint's graph neighborhood, then retrieves active tasks, open
decisions, explicitly approved shared sources, and bounded topic matches. General
profiles also include broader recent activity; coding profiles exclude that
unscoped feed.
Filter-only search supplies an epoch after_date to obtain BM's newest-first order
without excluding long-idle modern sessions. Coding-session retrieval is
repository-scoped; topic queries retrieve tasks and decisions only. The inserted brief is bounded and labeled as
untrusted historical reference, not current repository facts.

## Failure and privacy policy

Automatic-memory failure is visible but does not stop coding. Host observation
hooks are awaited, not veto hooks; a failed write can precede a compaction that
continues. Only a confirmed checkpoint is referenced afterward. Closing always
releases MCP, even if summary generation fails. No shutdown promise applies to
process kills. No ambiguous remote write is retried or overwritten automatically.

Common credential patterns are masked before automatic capture and in generated
output, but arbitrary public-text secrets cannot be reliably detected. Controls
and destination disclosure are part of the privacy boundary. No raw tool payloads,
hidden reasoning, model credentials, or arbitrary server error text are captured.

## Evidence

Tests cover real host registration, persisted sessions, paginated stdio tools,
source-tip deduplication, branch lineage, all compaction paths, write/receipt
failures, cancellation, shutdown, fresh resume, and headless TUI reload. The real-BM
suite proves file writes, reads, searches, transcripts, checkpoints, compaction
reference restoration, reload and resume in temporary local projects. Synthesis
uses deterministic providers, so these tests do not claim live-model quality or
paid/cloud account end-to-end verification.

## Follow-up boundary

A Tau sidebar can expose the active destination, recall sources, confirmed
checkpoint, and unfinished tasks through the supported extension UI. That is a
separate change after this contract is verified; a custom frontend is not required
for correct memory, and this package makes no sidebar/frontend behavior claims.