/basic-memory-setup

name: basic-memory-setup
description: Guide Basic Memory setup in Tau. Use when a user wants to install or configure the Tau memory extension, choose a memory destination or capture policy, verify connectivity, or troubleshoot setup. Check compatibility and obtain approval before installation, configuration changes, or test writes.

Set up Basic Memory in Tau

Help the user choose where memory goes and what gets saved. Ask one decision at a time. Set up Basic Memory's shared workflow: schema-backed checkpoints, tasks, decisions, categorized observations, and verified relations that other agents can find. Tau provides the lifecycle callbacks; it does not define a separate memory system. Do not create projects, reorganize notes, change credentials, or install packages as incidental setup work.

1. Inspect before changing anything

• Locate the integration directory: the installed `~/.tau/extensions/basic-memory`

from `bm install tau`, or `integrations/tau` in an explicitly identified Basic Memory checkout. Do not assume the current directory or this skill's directory contains the extension. A packaged install does not require a source checkout.

• Read the integration directory's `README.md`, `pyproject.toml`, `bridge.py`, and

`knowledge.py` for installation instructions, the dependency pin, Settings, and the general/coding profile models. Published reference: https://github.com/basicmachines-co/basic-memory/blob/feat-tau-1487/integrations/tau/README.md

• Check executable availability with `command -v uv`, `command -v bm`, and

`command -v tau`. Inspect versions/help only for executables that exist. The integration requires Python 3.13+, uv, and a configured Basic Memory CLI.

• Distinguish the user's installed Tau from the isolated integration environment.

Stock Tau 0.4.1 lacks continuity APIs. The upstream contribution is https://github.com/huggingface/tau/pull/687, from Basic Machines. Use the checked-in immutable dependency pin, not an invented version or a moving branch. A version string alone cannot distinguish stock 0.4.1 from its compatible fork.

• Identify the effective config path: `TAU_BASIC_MEMORY_CONFIG` if explicitly set,

otherwise `~/.tau/basic-memory.json`. Inspect only that file, not unrelated Tau catalogs, credentials, logs, or conversation storage. Never dump its contents into output. Do not accept repository-local config as a capture destination.

• If the extension is loaded, ask the user to run `/bm-status`. A text reply does

not run a slash command or control the current Tau session. Do not start a second Tau process against the current session's storage.

If prerequisites are absent, explain the missing prerequisite and obtain approval for the specific installation. Consult current Basic Memory install docs rather than guessing package versions or changing the user's global Tau installation.

2. Choose destination and policy

Offer **tools only**, **recall only**, or **full continuity**. Recommend full continuity for ordinary coding only after explaining its costs and disclosure.

For recall or continuity, list existing projects using the advertised `bm_list_memory_projects` tool when available, or `bm project list`. Check current CLI help or tool schemas for routing arguments. Identify local/cloud/team routing for the exact destination; if routing cannot be established, stop and ask. Do not dump Basic Memory's config or authentication material. Ask the user to choose an existing project explicitly, including its workspace when applicable. Never select the default project or a team workspace on the user's behalf.

Explain:

• Full continuity sends new public user/final-assistant text and the prior handoff

to Tau's active model for synthesis. It adds requests, latency, and model billing.

• Notes are saved to the selected Basic Memory project. Cloud/team destinations

disclose those notes there; get explicit approval for that destination.

• Recall-only still retrieves note contents into Tau's model context. Local notes

do not imply local model inference. It disables automatic writes, not explicit tool calls or `/bm-checkpoint` and `/bm-remember` requests.

• Transcripts stay off unless separately requested. Hidden reasoning, raw tool

payloads, and images are excluded from automatic capture. Credential masking is best-effort, not a general secret detector. Recommend tools-only for sensitive sessions; even explicit tool calls can disclose data.

Also ask about optional `read_projects` (up to six explicit read-only sources). Explain that shared context does not authorize writes back to those projects. Choose `placement_conventions` based on a small approved inspection of existing notes. Checkpoints belong in their configured folder; durable decisions and tasks belong with their topics, linked from checkpoints rather than duplicated each turn.

Use these policy overlays, replacing `CHOSEN_PROJECT` only after approval:

Tools only

{
  "project": null,
  "auto_recall": false,
  "capture_knowledge": false,
  "checkpoint_on_compact": false,
  "summarize_on_shutdown": false,
  "capture_transcript": false
}

Recall only

{
  "project": "CHOSEN_PROJECT",
  "auto_recall": true,
  "capture_knowledge": false,
  "checkpoint_on_compact": false,
  "summarize_on_shutdown": false,
  "capture_transcript": false
}

Full continuity

{
  "project": "CHOSEN_PROJECT",
  "auto_recall": true,
  "capture_knowledge": true,
  "checkpoint_on_compact": true,
  "summarize_on_shutdown": true,
  "capture_transcript": false
}

Coding sessions default to `tau/{repo name}` within the chosen project, using the final component of the confirmed repository identity, not the worktree directory name. General sessions default to `tau/checkpoints`; separately enabled transcripts use `tau/transcripts`. Omit `checkpoint_folder` (or use null) for automatic placement; set it explicitly only for a user-approved ov