# Second Brain

> Capture notes, ideas, and links, then ask them — for anyone (students, founders, knowledge workers).

## What it is — a personal knowledge base you can ask

Second Brain is a personal knowledge base you talk to. You capture notes, ideas, and links as you go, and later you just ask — "what did I note about onboarding?" — and it recalls by meaning, not by exact keyword match. It is the canonical exemplar of an agent's long-term, semantic recall: one `note` schema, hybrid-indexed, so the right note surfaces even when your question uses different words than the note did.

## What `bootstrap` provisions

`vectros bootstrap --blueprint second-brain` provisions a complete, no-code knowledge base from the bundled blueprint. Accurate to `packages/blueprints/src/blueprints/second-brain.ts`:

- **A `note` schema** (display name "Note"), indexed `HYBRID` — keyword matching on the title plus semantic matching on the body, so recall works by meaning. Its fields:
  - `title` — string, required, searchable.
  - `body` — string, searchable. The note itself, and the RAG-able body you ask questions against.
  - `tags` — string array, filterable. Freeform labels like `"idea"`, `"reading"`, `"work"`.
  - `source` — string, filterable, enum `['thought', 'web', 'meeting', 'book', 'article', 'other']`. Where it came from.
  - `status` — enum `['active', 'archived']`, filterable. Notes are archived, never lost.
  - `capturedAt` — date. When the note was captured; range-queryable ("notes from last week").
  - Each note also carries a first-class `externalId` — the caller-stable dedup/upsert key, sent top-level (not a declared payload field) — so re-capturing the same note converges instead of duplicating.
- **Lookup fields for three access patterns** — each a permanent choice (a field's lookup shape is locked once the schema is live):
  - `source` (equality, sorted by `lastUpdated`) — enumerate notes from one source, most-recently-touched first ("all notes from `meeting`"). `lastUpdated` is always present, so the sort never drops a note.
  - `status` (equality) — "show `archived` notes".
  - `capturedAt` (**range**) — ordered date windows ("notes from last week").
  (`source`/`status` are also filterable, to narrow a `hybrid_search`; `externalId` has a built-in finder for exact retrieval + idempotent upsert.)
- **A least-privilege access profile** — `allowedActions: ['records:r', 'records:c', 'records:u', 'search:r', 'schemas:r', 'inference:r']`. Read, create, update, search, schema discovery, and `inference:r` so the agent can `rag_ask` a grounded, cited question over your notes. Note the deliberate absence of `records:d`: a note is archived via a `status` flip, never deleted.
- **A service principal** (`externalId: 'second-brain'`, display name "Second Brain") that owns the context.
- **One seed note** — "Welcome to your Second Brain" — so the base is non-empty on first ask.

Everything lands in a dedicated app context (`contextId: 'second-brain'`, "Second Brain"), isolated from your other data.

## Before you start

This is an invite-only 0.x preview, so there are honest prerequisites. You need **early-access** to the Vectros platform and a **Cognito bridge token** from the developer portal — a one-time human step that authenticates the CLI to your tenant. You also need Node available so you can run the CLI via `npx`. Once you have the bridge token in hand, the bootstrap itself is a single command and the rest is no-code.

## 1. Bootstrap the blueprint

```bash
# install once: npm i -g @vectros-ai/cli  (or use npx @vectros-ai/cli, below)
npx @vectros-ai/cli bootstrap --blueprint second-brain
```

This runs the full blueprint lifecycle in one idempotent pass: it creates the `note` schema, the `second-brain` app context, the service principal, and the gated access profile, then mints a **narrow `ssk_*` scoped key** carrying exactly the six actions above (`records:r/c/u`, `search:r`, `schemas:r`, `inference:r` — no delete, no control-plane). Finally it seeds the welcome note.

The minted `ssk_*` is **auto-merged into your Claude Desktop config**, so the agent can start driving the knowledge base immediately; for Cursor, Cline, or another MCP client, pass `--print` and paste the printed `mcpServers.vectros` block into that client's config. Re-running the command is safe — stable identifiers (the service principal's `externalId`, each note's `externalId`) make the loader converge rather than duplicate.

## 2. Use it (no code)

With the `ssk_*` wired into your MCP client, you drive Second Brain entirely through conversation. The agent has the data-plane MCP tools — `record_create`, `record_query`, `hybrid_search`, `rag_ask`, and `list_schemas` — and nothing else. A few example interactions:

- **Capture a thought.** "Capture this: our onboarding drop-off spikes at the email-verification step — worth A/B testing a magic-link flow." The agent calls `record_create` to write a `note` (body set, `source: "thought"`, `status: "active"`, a generated `externalId`).
- **Find something by meaning.** "What did I note about user onboarding?" The agent runs `hybrid_search` over your notes and returns the matching ones — including that drop-off note, even though you said "user onboarding" and the note said "onboarding drop-off."
- **Enumerate a slice.** "List everything I saved from meetings" / "show my archived notes." The agent calls `record_query` in lookup mode on the non-unique `source`/`status` fields (or list mode to page the whole `note` type) — the deterministic, no-query counterpart to semantic search. A second-brain needs both: *recall by meaning* and *list what I have*.
- **Ask a grounded question.** "Summarize everything I've captured about retention." The agent uses `rag_ask` to answer from your notes, **with citations** back to the specific notes it drew from.

Prefer a UI? The generic Vectros data-plane app can browse, filter, and edit the same `note` records directly — same data, same context, a point-and-click alternative to the conversational path.

## 3. See it work

The "aha" is semantic recall. Capture a note about **"cutting churn by re-engaging dormant accounts,"** then later ask **"how do I keep customers from leaving?"** — you never used the word "churn," but Second Brain finds the note anyway, because `hybrid_search` matches on meaning, not just shared keywords.

Then ask a question instead of searching — "what ideas have I saved for reducing churn?" — and `rag_ask` answers in prose grounded in your actual notes, naming the source notes each claim drew from. That is the whole pitch: your scattered captures become something you can ask, and trust the answer because it tells you which notes it came from. (Citations name the notes today; one-click click-through to the source arrives with a later backend update.)

## How it maps to Vectros

- **Records** — each note is a schema-validated `note` record; `record_create` writes them, `record_query` reads them back.
- **HYBRID search** — the `note` schema's `HYBRID` index combines keyword (title) and semantic (body) recall; `hybrid_search` is how "find by meaning" works.
- **RAG / ask, grounded with citations** — `rag_ask` answers questions from the `body` text of your notes and returns citations to the source notes.
- **Lookups — exact, enumerate, *and* range** — `externalId`'s built-in finder retrieves a known note exactly (and is the upsert key that keeps re-captures from duplicating); the non-unique `source`/`status` lookups let `record_query` enumerate a slice; and the `capturedAt` range lookup pulls an ordered date window — all without a search. Lookup and search are complementary, not redundant.
- **Version history** — writes to the `note` schema accumulate immutable version rows, so the edit history of every note is preserved — and archiving (status → `archived`) keeps the record instead of deleting it.

## Notes & limits

- **You supply the content.** The agent does **not** scrape the web — there are no web-fetch or web-search tools in this surface. To capture a link or an article, you paste the text in; the agent stores what you give it.
- **The bridge token is a real step.** Bootstrapping needs early-access plus a Cognito bridge token from the dev portal — a one-time human action, not yet self-serve.
- **Synthetic data only** in this preview. Treat anything you capture here as illustrative, not a system of record for sensitive material.
- **One note at a time.** The conversational flow captures notes individually; there is no bulk import in this no-code path today.