feat(integrations): give Tau persistent Basic Memory continuity and full MCP tools

[phernandez]

Why

The Tau integration must provide continuity, not merely tool access. A fresh, resumed, or compacted session should recover the objective, decisions, unfinished work, and next action without making the user explain everything again. Knowledge should remain useful across Tau, Hermes, OpenClaw, Claude, and Codex through the same Basic Memory graph.

Reference: https://docs.basicmemory.com/reference/ai-assistant-guide and https://docs.basicmemory.com/concepts/vs-built-in-memory. Hermes and OpenClaw are implementation references for persistent MCP access and automatic capture.

Scope and implementation plan

1. Add a Tau-native package in integrations/tau/ using supported extension APIs. Verify synchronous setup versus asynchronous MCP discovery and lifecycle timing before selecting the bridge design.
2. Maintain a persistent MCP connection. Discover every page of tools/list and expose every server-advertised tool with its real name, description, and input schema. Namespace host tools to avoid collisions, retain MCP names for forwarding, and respect server feature gates.
3. Forward calls without reimplementing routing, authentication, or domain behavior. Preserve structured results, content, and error status. No automatic retries of ambiguous writes or claims of saving without a successful result.
4. Automatic recall on session start/resume: load bounded relevant context from configured projects, including active work, decisions, and checkpoints. Recovered notes are evidence, not executable instructions. Check live repository state before treating a recovered coding checkpoint as current.
5. Capture as work progresses: contribute instructions and shared memory workflows that encourage recording durable decisions, findings, and context with observations and relations, updating existing notes instead of duplicating them.
6. Automatic compaction checkpoints: persist useful resumable context at the supported compaction boundary and restore its reference afterward. Verify callback timing and context availability. Do not assume an event name guarantees an awaited pre-compaction barrier. If Tau lacks a required public seam, report the blocker and propose an upstream change rather than silently substituting a weaker behavior.
7. Configurable transcript capture and session summaries: keep raw conversation records distinct from synthesized knowledge and link summaries/checkpoints to their source when captured. Provide clear capture controls and destination disclosure. Exclude secrets, hidden reasoning, and raw tool-output dumps from automatic transcript capture. Define replay/deduplication and branch/resume semantics.
8. Explicit orientation, checkpoint, remember, and status workflows complement automation. Status reports connection, project routing, recall/capture/checkpoint state, and failures. Automatic writes require a resolved, configured destination; never guess a team target.
9. Document installation, dependency setup, configuration, local/cloud routing, capture defaults, and lifecycle behavior. No silent dependency installation, project creation, or credential changes.
10. Add bridge/lifecycle tests, actual Tau extension-loading tests, and isolated real Basic Memory round trips. Wire package checks and CI.

Acceptance criteria

• Every advertised MCP tool is available with its original input schema, including pagination and tools absent from existing curated integrations.
• Explicit project/workspace arguments reach Basic Memory unchanged.
• A new session recovers previous work without a manual orientation command. Recall stays bounded and cites actual returned note identifiers.
• Compaction preserves the objective, decisions, unfinished work, verification, and next action in durable memory; the next context can find that checkpoint.
• Capture controls are honored, replays do not duplicate conversation segments, and failed writes remain visible rather than being marked saved.
• Transcript capture is distinguishable from synthesized knowledge. Knowledge notes remain portable and usable by another agent.
• MCP sessions and child processes close on failure, cancellation, shutdown, and reload without duplicate registrations or background writers surviving retirement.
• Errors are actionable. Automatic memory failures do not masquerade as success or unnecessarily stop the coding session.
• Text, structured content, and non-text results are tested; unsupported types are surfaced explicitly, not silently discarded.
• Tests exercise fresh-session recall, capture, compaction continuity, disable controls, reload/resume, failure, and cancellation. Real read/search/write verification uses temporary projects, not production data.
• Existing integrations remain unchanged except necessary shared packaging wiring.

Out of scope

Generalized MCP hosting inside Tau core and edits to installed Tau Python files. Missing public extension capabilities should receive a separate upstream proposal, not a local package patch.

Delivery

Worktree: ../basic-memory-tau-1487, branch feat-tau-1487. Submit a signed-off PR linked here, run package/static/targeted integration verification, and enter the latest-head review loop. No merge without authorization.

[claude]

Claude finished @phernandez's task in 28s —— View job

---

Triage

Type: Enhancement (feature request) — labeled enhancement.

Component: Integrations (new integrations/tau/ package, following the existing integrations/hermes and integrations/openclaw pattern). Not cloud-specific, so no cloud label applied.

Priority: Medium — adds a new supported integration surface; doesn't affect existing users or fix a defect, but is a meaningful capability expansion.

Complexity: Complex — a new host integration requiring MCP client lifecycle management (session/process ownership, paginated tools/list discovery, dynamic tool registration with original schemas), call forwarding without duplicating auth/routing, new orientation/checkpoint/status commands, documentation, hermetic + extension-loading + live round-trip tests, and CI/package-check wiring. Comparable in scope to the existing Hermes and OpenClaw integrations.

No duplicate issues found via gh search issues for Tau integration/extension work.

The issue itself is well-specified (clear why, plan, acceptance criteria, and explicit out-of-scope boundaries), so no clarifying questions are needed before implementation begins.

[phernandez]

Implementation preview is in draft PR #1489. All advertised MCP tools, persistent calls, bounded automatic recall, opt-in public-message capture, and explicit/overflow-triggered checkpoint workflows are implemented. 18 tests pass including an isolated real Basic Memory write/read/search and fresh Tau-runtime recall; runtime modules have 100% statement coverage. Package/static/doctor checks passed locally. Full continuity remains open: upstream huggingface/tau#506 covers missing normal/manual compaction events; durable replay/branch lineage, richer task-oriented recall, and shutdown summaries remain follow-ups. No installed Tau files or user memory configuration were changed.

[phernandez]

Tau upstream dependencies and lifecycle coverage

Tracking note for draft #1489. This separates confirmed host gaps from unfinished Basic Memory integration work.

Current lifecycle coverage

Lifecycle	Preview behavior
Session start	Opens the persistent MCP connection. With an explicit project and auto_recall enabled, queues bounded recent_activity results as reference context, without starting a model turn. This is recent-feed recall, not full task/decision reconstruction.
Compaction start	No Basic Memory handler registered yet. No guaranteed pre-compaction checkpoint.
Compaction end	Successful overflow compaction queues a checkpoint instruction for the agent. It does not itself write a note or acknowledge persistence. Normal/manual compaction does not deliver this notification in the inspected host.
Message end	Opt-in public user/final-assistant text capture, with structured write receipt validation.
Shutdown	Closes the MCP connection. No synthesized shutdown summary yet.

Upstream work

1. Confirmed dependency: consistent compaction lifecycle events. Automatic threshold compaction is invisible in the TUI (no compaction events emitted) huggingface/tau#506 is open; it is an issue, not a landed PR. Threshold and manual paths need the same start/end contract as overflow, including aborted/failure outcomes and no duplicate notifications. No separate upstream implementation PR has been opened by this integration work.
2. Acceptance requirement to verify with that fix: awaited pre-compaction persistence. A start notification must run before active context is replaced and allow an extension's bounded asynchronous write to finish. Merely adding an end event or queueing a model instruction is insufficient. First verify whether the consistent existing event interface satisfies this; do not invent a second API or assume #506 automatically delivers durable checkpointing. The BM handler, checkpoint contents, receipts, and failure policy are still our responsibility.
3. Candidate upstream follow-up, not yet a proven hard dependency: persisted-entry notifications. In installed Tau 0.4.1, entry_appended is declared but _append_session_entry only persists storage. Emitting actual committed entry identity could support durable replay/branch reconciliation. Investigate supported session-entry APIs before requiring a separate upstream PR. Never substitute session-file scraping or installed-package patches.

Work remaining in Basic Memory (not automatically fixed upstream)

• Implement pre-compaction checkpoint persistence and test manual, threshold, overflow, abort, and write failure against real host paths.
• Richer startup orientation: relevant active task, decisions, latest checkpoint, verified next action, rather than only a recent feed.
• Durable replay/deduplication across reload/resume and explicit branch lineage.
• Shutdown summary policy and implementation.
• Live TUI reload and real-model checkpoint verification. Synthetic event tests do not establish either.

Priority: complete the awaited compaction path first, then checkpoint-aware startup recall. Those two make the continuity loop useful; all-tools registration alone does not fulfill it.

[phernandez]

Continuity implementation and upstream dependency

The previous preview/follow-up list is superseded by #1489 at 9ef032517. Startup recall, ongoing synthesized capture, awaited pre-compaction writes, restored references, configurable transcripts, shutdown summaries, persistent receipt reconciliation, and branch/resume behavior are implemented and tested.

Required upstream PR: huggingface/tau#683, implemented in phernandez/tau and pinned at f41242532a2e55c6ee7f96b71d6949d3db9c172d in the isolated integration environment. It adds consistent compaction extension callbacks, persisted active-branch inspection, bounded tool-free active-model synthesis, zero-turn reference insertion, and in-place tree-branch lifecycle notifications. No installed Tau files were changed.

The earlier candidate entry_appended dependency is unnecessary: active-branch entries provide durable receipt reconstruction. Tau #506 stays open for separate frontend iterator/TUI-status work; the extension's manual/threshold/overflow callbacks no longer depend on waiting for that entire issue.

Verification: 51 integration tests pass with 100% statement coverage of all five runtime modules. Real BM tests use temporary local projects and prove transcript/checkpoint persistence, read/search, compaction reference restoration, reload and fresh resume. Actual Tau session, branch/replay, cancellation/failure, and headless Textual /reload tests pass. Root fast-check/typecheck, all consolidated package checks, and doctor pass. Upstream fork: 1881 passed, 2 Windows-only tests skipped, Ruff/mypy passed.

The package requires the pinned fork until upstream releases these APIs. Automatic memory failures remain visible; observation callbacks are awaited, not compaction vetoes. Common credential masking does not guarantee removal of unknown public-text secrets. No paid live-model, production-memory, or cloud-account test was performed. Codex approved 9ef0325 with a fresh thumbs-up and no unresolved findings. Tau/package/static CI is green; broader repository CI and upstream maintainer review remain pending. No merge is authorized.