<p align="center"> <img src="./assets/github-banner.jpg" alt="Bastra — the open memory layer for AI assistants and agents" width="100%" /> </p>

Bastra.Recall

A persistent teammate memory for your AI assistants — one local vault, shared by every tool that speaks MCP. Ein persistentes Teammate-Gedächtnis für deine AI-Assistenten — ein lokaler Vault, geteilt von jedem Tool, das MCP spricht.

---

🇬🇧 English

What it is — A long-term memory for your AI assistant. Whenever you correct it, state a rule, or commit to a decision, it gets saved as a small note. In your next chat — days or weeks later — the AI pulls those notes back automatically. No more repeating yourself. Everything stays on your own Mac as plain Markdown files (Obsidian-compatible), and every connected tool shares the same memory at the same time. Today that includes Claude Code, Claude Desktop, Codex, and the ChatGPT desktop app — see the support matrix below for what's wired and what's next.

Status — 🟢 Early beta, v0.9.x. v0.9 "Honest numbers, nothing silently lost" is out — 45 issues against the class of bug where nothing fails, nothing is logged, and the number you are shown is not true. Next is the V1.0 release contract: a reproducibly measured, selective, controllable recall base, fully specified. See PLAN.md.

Supported surfaces

| Surface | Status | Notes | |---|---|---| | Claude Code | ✅ tested — in daily use | MCP + Skill + seven quiet hooks + statusline | | Claude Desktop | ✅ tested | MCP + Skill, autonomous session context without hooks; .mcpb double-click extension | | Codex + ChatGPT Desktop | ✅ implemented for v1.0 | one shared local MCP config + Skill + seven Codex-native quiet hooks; bastra install codex | | Cursor | 🟡 implemented | installs and registers cleanly; implemented, but not yet field-tested | | ChatGPT (Custom GPT Actions) | 🗺️ planned | the REST gateway and an OpenAPI starter spec ship today; the packaged Custom-GPT action is next in line — tracked in #13 |

Anything else that speaks MCP can attach through the forwarder today — untested surfaces are exactly that, and field reports are welcome. Non-MCP clients can use the REST API (docs/USAGE.md).

Supported platforms

This table and the one above are the support matrix: the Homebrew caveat, the npm package README and the package descriptions state the same set, and a test holds them to it (#525).

| Platform | Status | What you get, what you don't | |---|---|---| | macOS (Apple Silicon and Intel) | ✅ supported | Everything: the Homebrew install path, bastra autostart (LaunchAgent), the .mcpb Claude Desktop extension, open_document, and the compiled hook client. | | Linux (x86_64 and arm64) | 🟡 daemon, CLI, MCP and hooks | Install with npm (npm i -g bastra-recall); the compiled hook client ships for both architectures. Not available there: bastra autostart (the LaunchAgent is macOS-only — the MCP forwarder starts the daemon on demand instead), the .mcpb extension install, open_document, and the Homebrew path. | | Windows | 🗺️ not covered | No compiled hook client is built for it, and nothing here is tested on it. |

Why

Working with an AI assistant over months means re-explaining the same things. Pitfalls it already learned in one project recur in the next. Stable preferences ("give me a recommendation, not a 5-option menu") get forgotten between sessions. Project-specific facts get re-discovered every time.

Most AI tools have memory features, but they're passive: a static index file at best, no proactive recall, no cross-surface continuity.

The cost isn't just frustration — it's that the user ends up thinking for the AI. "Wait, didn't we solve this last week?" That's the bug.

What bastra-recall does

A persistent memory layer that:

• Saves autonomously — when a lesson is learned (frustration, repeated correction, durable preference, finalized decision), the AI writes it to the vault without being asked. Trigger discipline ships as a shared ChatGPT/Codex/Claude Skill; client-native hooks add the reflex layer where supported.
• Recalls before acting — not only when the user prompts. The AI is instructed to query the vault before writing code, before plans, and at session start. The highest-weighted search field is recall_when, declared at save time.
• Works across surfaces — one local daemon serves all your connected AI tools at once, over MCP or HTTP. One vault, one index, shared state (see the support matrix above).
• Plain markdown, Obsidian-compatible — the vault is a folder of .md files with YAML frontmatter. Edit in Obsidian, in the AI, or by hand. Vaults on Google Drive / iCloud / Dropbox mounts are supported via automatic polling-mode in the file watcher.

<p align="center"> <img src="./assets/memory-save-ack.png" alt="An autonomous save confirmation in the terminal: → saved: … (salience 0.85)" width="100%" /> <br/> _{<em>An autonomous save: the AI spots a recurring pattern (here the third occurrence), records the lesson itself and weights it by salience — you just see the one-line confirmation, no prompting needed.</em>} </p>

The single success metric

The user doesn't have to think for the AI anymore.

If recurring mistakes still recur, if the user still has to re-state preferences each session — the project failed, regardless of how clean the architecture is.

How it works

flowchart TB
    CC["Claude Code"]
    CD["Claude Desktop"]
    CU["Cursor"]
    OX["Codex + ChatGPT Desktop"]
    WEB["REST clients<br/>(web apps, scripts)"]

    CC -->|stdio MCP| FWD["MCP forwarder<br/>stdio to HTTP"]
    CD -->|stdio MCP| FWD
    CU -->|stdio MCP| FWD
    OX -->|stdio MCP| FWD
    WEB -->|"REST /api/v1 + token"| D
    CC -.->|"hooks: recall before edits,<br/>context at session start"| D
    OX -.->|"Codex hooks: recall before patches/plans,<br/>context at session start"| D

    FWD --> D["bastra-recall daemon<br/>127.0.0.1:6723<br/>one process for every client"]
    D --> IDX["BM25 index<br/>+ optional embeddings"]
    IDX --> V[("Your vault<br/>plain markdown + YAML<br/>on your disk")]

    D -.->|"save_memory writes a file,<br/>then re-indexes it"| V

Everything above runs on your machine. Your vault content — memories, documents and the recall queries themselves — never leaves it unless you deliberately opt in: either by choosing the OpenAI embedding provider (bastra config set embedding.provider openai, which POSTs your queries and the indexed memory text to api.openai.com) or by pointing a tunnel at the REST gateway yourself. A generic OPENAI_API_KEY sitting in your environment for some other tool does not count as that choice — recall stays keyword-only until you say so (#520). A few optional features do talk to the network without sending vault content: the update check (BASTRA_UPDATE_CHECK=off), the statusline pricing refresh, the vault map's weather/geocoding lookup (coarse location only) and opt-in Bastra Commons sync. Recall is hybrid — an in-memory BM25 index (with recall_when weighted highest) plus an optional local embedding pass, fused via RRF. In Claude Code and Codex/ChatGPT desktop, seven quiet hooks recall before edits or patches, at session start, before plans, before a claim about measured project state goes into text someone else reads, and after failed commands.

Details: docs/architecture.md · docs/hooks.md · docs/triggers.md · docs/USAGE.md.

Memory shape

Each memory is a markdown file with structured frontmatter:

---
id: css-input-focus-ring-stacking
title: "Don't stack focus styles on inputs"
type: lesson
summary: "Stacking ring + outline + custom :focus on nested inputs causes double focus rings. Use single :focus-visible."
topic_path: [css, input, focus]
tags: [css, input, focus-ring, ui-bug]
scope: all-projects
recall_when:
  - creating new input component
  - writing input or form css
  - focus or accessibility styling
related: [css-effects-stacking-antipattern]
source: "carnexus, recurring lesson"
confidence: 0.95
---

The recall_when field is the bridge between save and recall: when saving, the AI declares the contexts under which future sessions should be reminded. Full field semantics and examples: docs/memory-schema.md.

Install

A) One command — easiest, for non-coders

curl -fsSL https://bastra.io/install | bash

Paste it into Terminal, press Return, answer the setup questions. It installs Homebrew if it's missing, adds the bastra tap, installs bastra-recall, and hands over to the guided setup — no terminal knowledge beyond pasting one line. Then restart Claude Code / Claude Desktop / Codex / ChatGPT Desktop / Cursor. To read the script before running it, open bastra.io/install; it is the same file as distribution/install.sh.

Alternative — double-click. Download Install Bastra.command from the latest GitHub release, then right-click → Open and confirm the dialog. A plain double-click does not work: macOS quarantines every browser download, so Gatekeeper blocks it. If macOS then refuses with a permissions error, the download also lost its executable bit — chmod +x ~/Downloads/Install*.command restores it. The same applies to Uninstall Bastra.command, which unregisters every client and stops the daemon, never deleting a memory.

B) npm or from source — for developers

npx bastra-recall install           # zero-install: guided setup with selection lists
# or:
npm install -g bastra-recall && bastra install
# or from source (Node 22+, Git):
git clone https://github.com/n0mad-ai/bastra-recall.git && cd bastra-recall
npm install && npm run build
node packages/daemon/dist/cli.js install all --vault /abs/path/to/your/vault

bastra doctor checks (and --fix repairs) every registration. Every config write is idempotent, atomic, backed up, and parse-safe — details in docs/USAGE.md.

C) Fully manual — fallback

Add the MCP forwarder block to your client's config by hand: docs/USAGE.md.

Semantic recall (optional)

BM25 keyword search is the always-on default; a local embedding pass joins in once a provider is set up — one command, fully reversible:

bastra embeddings on       # installs Ollama (if missing), pulls the model, persists the choice
bastra embeddings off      # back to BM25 keyword-only — nothing breaks

Detail