@bastra-recall/daemon

The MCP server + HTTP gateway behind bastra-recall. Watches a markdown vault, indexes it with BM25 + optional embeddings, and exposes a stable tool surface over both stdio MCP and HTTP REST.

For project-level docs (vision, install, REST API, roadmap), see the top-level README and PLAN.md.

What it does

• Watches a directory of .md files with YAML frontmatter (schema in ../../docs/memory-schema.md).
• Indexes via minisearch BM25; recall_when is the highest-weighted field because it's authored for triggering.
• Hybrid recall: optional embeddings (Ollama or OpenAI) via Reciprocal Rank Fusion on top of BM25 — see BASTRA_EMBEDDING_PROVIDER.
• Save path: writes .md files, validates frontmatter (zod), force-reindexes so save+recall in the same turn are consistent.
• Auto-related enricher: for each new save, fills related_via with cosine ≥0.7 neighbors.
• Memory graph: multi-hop recall (expand_hops: 1) returns 1-hop neighbors via related_via.
• Sensitivity filter: private memories aren't visible to external MCP/REST callers — and since #464 not writable by them either. The permission is bound to the transport, not passed as a tool argument, and a refused read and a refused write answer alike, so neither is an existence oracle.
• Staleness re-ranking: memories with valid_until / expires_after_days / last_reviewed_at get demoted (or excluded if expired) at recall time.

Surfaces

Tools exposed (MCP + REST symmetric)

Install + register

See the top-level README. Paths, in order of friction:

1. curl -fsSL https://bastra.io/install | bash — installs Homebrew + tap + binary + runs the guided setup. The recommended non-developer path.
2. Install Bastra.command doubleclick — same steps, but a browser download is quarantined and mode 644, so it needs right-click → Open (#320).
3. bastra install all — single CLI call that registers MCP + Skill + the default quiet Hooks across Claude Code, Claude Desktop, Codex/ChatGPT Desktop, and Cursor. On a first run with no vault configured, an interactive install offers to create ~/BastraVault for you (non-interactive/--yes/--dry-run runs keep the deterministic error).
4. Fully manual JSON snippets — fallback.

All paths end with the client configs patched. Whether the daemon is already running differs: the interactive Map wizard starts it, and the MCP forwarder starts it on the first tool call — bastra install all only registers, it neither starts nor health-checks the daemon. bastra doctor is what probes the endpoint (#525). Use bastra doctor --fix to repair stale paths, missing required hooks, or a stale Skill copy after an update. The quiet Stop save-eval hook is enabled by default by the CLI. Opt out with bastra install claude-code --no-stop-hook; deliberately disabling this optional hook does not make Doctor fail.

Daemon process check

Don't grep for daemon/dist/index.js — the daemon is often launched with a relative path (node dist/index.js) and won't match. Use the port instead:

lsof -i :6723 -P -n      # who owns the daemon port
curl -sS http://127.0.0.1:6723/health

Exactly one PID should be listed. Two means a stale daemon is running in parallel — the HTTP port goes to whichever bound first, and the loser exits silently (see the EADDRINUSE handler in http-listen.ts).

Daemon startup

The MCP forwarder uses one shared daemon, giving an installed managed macOS service up to ten seconds before fallback spawn. For REST clients that need the daemon before an MCP client connects, start it explicitly:

bastra-recall &

Dev workflow

npm run dev                # ts-watch via tsx (no compile step)
npm run build              # tsc + chmod +x all dist binaries
npm run check:types        # type-check only
npm run smoke              # smoke-test recall against fixtures/sample-vault
npm run smoke:telemetry    # smoke-test telemetry append
npm run backfill:related   # populate related_via on legacy memories

Configuration (environment variables)

Every on/off switch reads 0, false, off or no as off and 1, true, on or yes as on, in any case; the table shows the canonical spelling.

Telemetry

Every recall, load_memory, save_memory and hook call appends one JSON line to events-YYYY-MM-DD.jsonl in the log dir. Each daemon process gets a fresh session_id; recalls get a recall_id and any load_memory / save_memory within 5 minutes references that id as follows_recall.

That's enough to compute:

• recalls per session, hit counts, top-score distribution, latency p50/p95
• recall→load_memory follow-through rate (proxy for "was the hint useful?")
• saves per session, type/scope distribution, % overwrite vs. new
• save→follows_recall rate (was a duplicate-check done?)
• per-hook latency and hit-quality (where do PreToolUse / SessionStart actually help?)

Logs live outside the vault on purpose so the file watcher doesn't index them. Tail one to watch live: tail -f ~/.bastra/logs/events-$(date +%F).jsonl.

Search ranking

Field boosts (in src/search.ts):

recall_when_flat:          5    ← authored for triggering, highest weight
title:                     4
tags_flat:                 3
recall_when_expanded_flat: 2    ← doc2query paraphrases (#117): machine-generated, below the author's words
topic_path_flat:           2
summary:                   2
body:                      1

Fuzzy distance 0.2, prefix matching enabled, combineWith: "OR". Hybrid mode combines BM25 with embedding cosine via Reciprocal Rank Fusion (RRF); the embedding query goes to the provider once per recall and is cached in-memory.

Schema reference

See ../../docs/memory-schema.md for the full memory frontmatter spec. The daemon enforces required fields via zod on load — files that fail validation are skipped with a warning to stderr.

Limitations

• Shared process. The forwarder starts the daemon on demand. On macOS, bastra autostart on manages an optional LaunchAgent for keeping it running; use bastra autostart off to return to on-demand operation.
• Cloud-storage mounts (Google Drive, iCloud, Dropbox) need polling-mode in chokidar — enabled by default, but watcher latency can be a few seconds.
• Cursor rules are per project. bastra install cursor registers MCP. Run bastra rules cursor inside each project to install the shared memory guidance.