Basic Memory Setup

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

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

Recall only

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

Full continuity

jsonCopy code
{
  "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 override. Preserve existing folder, command, arguments, timeout, and budget settings unless the user approves changing them. Never put API keys in this file; Basic Memory owns authentication and project routing.

General or coding profile

Ask whether this checkout is for coding or general work. Do not infer coding consent merely because Git is present. General checkpoints use session; coding checkpoints use the shared coding_session contract.

For coding, resolve the Git top-level root and stable repository identity, such as owner/name. Inspect remotes narrowly without echoing embedded credentials. Ask the user to confirm both; do not invent an identity when remotes are ambiguous. Explain that branch, SHA, cwd, and optional PR metadata are saved with checkpoints. The repository label is user-confirmed identity, not a write destination.

Store coding profiles only in the user-owned repositories list. Each entry has an absolute checkout root, repository, kind: coding, and its own explicit project/read sources/placement. It does not inherit the global project. The closest matching root wins; Git must confirm that exact root before a coding write. Register another worktree explicitly with the same repository identity. Never silently copy a parent's mapping into a nested Git checkout.

Example configuration for coding in one approved checkout and tools-only elsewhere (the global lifecycle flags still apply to every profile):

jsonCopy code
{
  "project": null,
  "repositories": [
    {
      "kind": "coding",
      "root": "/absolute/path/to/approved-checkout",
      "repository": "owner/repository",
      "project": "CHOSEN_PROJECT",
      "read_projects": [],
      "placement_conventions": "Decisions in decisions/, tasks in tasks/. Search before creating notes."
    }
  ],
  "auto_recall": true,
  "capture_knowledge": true,
  "checkpoint_on_compact": true,
  "summarize_on_shutdown": true,
  "capture_transcript": false
}

Do not replace other repository entries when updating this checkout. A general user-level project applies outside configured coding roots; confirm that broader scope explicitly. Opt-out flags disable automatic operations across profiles. Existing legacy Tau receipts remain usable; old notes are not silently rewritten to retrofit repository metadata.

3. Apply approved configuration

Show a safe summary of the proposed destination, policy, effective config path, and changes. Ask for approval before writing. These examples are overlays, not permission to overwrite an existing config wholesale.

Parse the existing JSON strictly. If malformed or containing unknown fields, stop and explain the problem without printing sensitive values; do not replace it with defaults. Merge the approved fields and validate the complete candidate using tau.bridge.Settings.model_validate in the integration's environment, before writing. Do not print the config, validation input values, or unfiltered exceptions. Report invalid field paths and a safe explanation. Validation must not start MCP or call a model. Preserve the existing file's permissions and use a private file for a new config; avoid leaving backups containing private arguments in the checkout.

Write only after successful validation. Report configuration validation separately from connection or end-to-end verification. If already configured correctly, leave it unchanged and proceed to verification.

Seed shared schemas with approval

Read the schema files in <integration-directory>/schemas/. They are bundled copies of the repository's integrations/shared/schemas/, shared with other hosts.

After restating the exact write project and receiving approval, search for existing schema notes and read any matching definitions. Offer missing schemas only:

• coding-session.md for coding, or session.md for general use.
• task.md and decision.md for both profiles.

Use the advertised bm_write_note schema with note_type="schema", directory schemas, the schema frontmatter as metadata, and Markdown body as content. Do not paste YAML frontmatter into the body. Disable overwrite. Do not replace a user's customized schema, even if it differs from the bundle. Explain incompatibilities and ask before making a separate migration. No empty folders, fabricated tasks, or lifecycle-event notes are required. Seeding does not require inventing a new captureEvents setting; Tau does not use the hook CLI's audit inbox.

4. Launch the compatible environment

For a packaged install, with approval for dependency installation, use:

bashCopy code
bm install tau --sync

Then give the user this command to run in their terminal:

bashCopy code
uv run --project ~/.tau/extensions/basic-memory tau

The installed extension is discovered automatically; do not also pass -e. For source development, with approval, run uv sync --project <integration-directory> and launch uv run --project <integration-directory> tau -e <integration-directory>. Use actual resolved paths, not the placeholder literally. Do not install a second copy alongside an existing source/copy install without choosing which one to keep.

This launches the pinned isolated environment, not the user's global Tau. bm install tau installs this setup skill and the prompt templates separately; loading from source alone does not discover them. Follow the README's manual skill-copy instructions when using source development.

In an already compatible Tau session, ask the user to /reload after config changes. Reload/replacement shuts down the old lifecycle first: if automatic capture was previously enabled, that shutdown can still write using the old settings. Warn before switching destinations or disabling capture. Editing config is not an immediate guarantee that the running session has stopped capturing.

5. Verify in stages

1. Config: the candidate passes the actual Settings model. This alone proves neither connectivity nor memory persistence.
2. Connection and structure: /bm-status reports connected and shows the intended project, general/coding profile, read sources, and controls. Confirm the selected schemas exist using read/search tools. If shared sources were configured, verify a read-only query in each approved source.
3. Recall: for recall/continuity policies, ask permission to retrieve an existing non-sensitive note, then use /bm-orient <topic> and confirm the note content was inserted. An empty project can connect successfully while having nothing to recall; report that distinction.
4. Optional write/read: obtain approval for a uniquely named, non-sensitive setup test note in the exact project. Use the advertised bm_write_note schema with overwrite disabled, then bm_read_note on the returned path. Compare content. Do not infer a save from a command acknowledgement or a successful search alone. An uncertain write must not be automatically retried.
5. Optional continuity: explain that /bm-checkpoint summarizes eligible public session content, not just a synthetic test marker, and can incur model charges. Obtain consent before asking the user to invoke it. Verify the saved path by reading it. Use advertised bm_schema_validate on that note when available. For coding, check repository/root/branch/SHA metadata and a repository filter query; then verify recall after an approved reload. Do not compact a working session merely as a setup test. A tool unavailable behind a feature gate is an unverified stage, not permission to enable features silently.

Ask separately before deleting any test note. Never delete checkpoints or receipts as automatic cleanup. Report what was actually tested and leave unrun stages explicitly unverified. Do not declare full continuity verified from write/read alone.

Troubleshooting and handoff

• Unsupported host: use the pinned environment; never patch installed Tau files.
• Disconnected: verify the configured executable and arguments, project access, and safe diagnostic status. Do not expose server stderr or credential values.
• Missing tools: use the advertised inventory and server feature gates. Do not invent tools or silently enable disabled server features.
• Failed/unconfirmed checkpoint: inspect availability and the confirmed path. /reload reconciles pending intents by reading; it is not a blind write retry.
• No project: automatic memory is intentionally off, not broken.
• To disable automatic memory, apply the tools-only overlay with approval and explain the old-lifecycle shutdown caveat before reload. Existing notes remain.

Finish with: chosen policy and destination, config path, compatible launch command, verified stages, remaining blockers, and /bm-status, /bm-orient, /bm-checkpoint, /bm-remember. No invented save confirmations or claims to have changed the current Tau session through a reply.