Folios & daily notes

Carabase has two surfaces where your content lives: daily notes, the date-bound journal of what happened, and folios, the topic-bound notebooks that gather everything about a subject. Connectors, imports, and the agent all write into these surfaces, and retrieval reads back out of them.

Daily notes

A daily_notes row exists for every calendar date you’ve used Carabase. Each row holds a Tiptap document — the same JSON structure your editor produces — which is a sequence of blocks. The most important block type is the logCard: a single thought captured in the moment, with optional tags, folio assignments, and a timestamp.

Daily notes are the append-only journal of your work. They fill from several sources:

• Connectors (GitHub PRs, calendar events, Gmail, and more) inject logCards onto the day an item belongs to.
• The dream cycle injects reflections nightly (around 3:30 AM).
• The agent injects progress updates from agentic flows.

Every injected logCard carries a stable sha256 idempotency key in its attrs. Re-running the same import or re-firing the same connector is a no-op — no duplicates, no merge headaches. You can also pass an Idempotency-Key header (or attrs.idempotencyKey) to POST /api/v1/daily-notes/inject to get the same guarantee from your own integrations.

Server-side tags and @mentions

When daily-note text is indexed, the host — not the client — authoritatively extracts #hashtags and @mention entity links from the text. Hashtags are de-duplicated into the note’s tag set (surfaced by GET /api/v1/tags), and @mention links are recorded against the entities they point at. This means the same tag and mention data is available everywhere, regardless of which client wrote the note.

Folios

A folios row is a topical notebook — “everything related to project X”, “my notes on this book”, “my taste in music”. Folios are the unified narrative substrate in Carabase: a single table backs both kinds of folio you’ll encounter:

• Collections — folios you create and curate by hand.
• Engine folios (taste, domain, project) — folios Carabase maintains for you, where an LLM synthesizes a cited narrative from your data.

Each folio has a name, a canonical slug, and (for engine folios) a synthesized narrative that’s refreshed automatically. Collection folios can also carry an auto-updated summary that the nightly synthesis pass appends to without overwriting your own prose.

Membership: pinned vs. auto

What’s “in” a folio is tracked in folio_members, and every member is one of two kinds:

• Pinned — placed deliberately and never evicted automatically. This covers prose you commit by hand, captured AI coding sessions, and artifacts brought in by source-linking (see below).
• Auto — gathered by the synthesis engine and replaced on each refresh. These are the evidence citations behind an engine folio’s narrative.

This split is load-bearing: the engine’s nightly refresh only ever touches auto members, so anything you pinned survives untouched.

How content gets into a folio

There are three paths, and they coexist:

1. Commit prose directly. Writing text into a folio — via the commit_to_folio MCP tool, the CLI, the importer, or the dream injector — chunks the text, embeds each chunk for retrieval, and adds it as pinned members. This is the single canonical write path for putting prose into a folio.
2. Route with sync rules. Connectors read a sync_rules row that says “for items matching these filters, inject logCards into this folio with these tags, and (optionally) feed them through the harvest pipeline for entity extraction.” A logCard belongs to a folio when its attrs.folios array names the folio (or it contains a folio-mention node). Multiple rules per connector are supported; routing is merged when an item matches more than one rule. See Sync rules.
3. Link an upstream source. You can declaratively link a folio to a source of truth — a GitHub repo, a Gmail label, a Google Calendar, or a Drive folder. The link compiles into a managed sync-rule entry, so new matching items route into the folio as pinned members automatically, and (for repos and calendars) you can opt into a one-time backfill of already-ingested items. Linking a repo also binds that project’s captured coding sessions and routes its issues and PRs into the folio.

Narrative synthesis for engine folios

Engine folios (taste, domain, project) don’t just collect items — they get a synthesized, cited narrative. A charter→gather→map→reduce pipeline reads your data, drafts a narrative, and cites each claim back to the artifact it came from. Those citations are the folio’s auto members. The narrative is rebuilt on a backfill and kept current by a nightly merge that folds in just the new material.

Several optional, default-off capabilities extend this:

• Photos can be surfaced into a folio: a vision model judges whether a candidate image actually fits, and a human approves it (requires image search to be enabled).
• Substrate evidence (e.g. listening history) can feed the narrative for relevant folios.
• Proactive priming can inject a folio’s lead summary into chat and agent prompts so the assistant already knows the context.

These are operator opt-ins, off by default.

Tags vs. folios

Tags (#meeting, #decision) are lightweight and shared across daily notes — good for ad-hoc filtering. Folios are heavier: they have a synthesis cycle, a summary, and an entry list — good for sustained topics. Tags and folios are independent metadata even when their names coincide. A logCard can carry many of both:

{
  "type": "logCard",
  "attrs": {
    "tags": "[\"meeting\", \"decision\"]",
    "folios": "[\"acmebase\", \"fundraise\"]",
    "timestamp": "10:42",
    "idempotencyKey": "<sha256>"
  },
  "content": [/* Tiptap children */]
}

Importing existing notes

Coming from Obsidian, Logseq, Notion, Bear, Apple Notes, Roam, or Reflect — or bringing AI chat history (ChatGPT, Claude.ai, Gemini via Google Takeout) or a social-media data export (Instagram, Facebook, LinkedIn, X bookmarks)? The importer at /admin/import parses your archive into the canonical Tiptap shape:

• Date-bound notes become logCards on the matching daily note.
• Free-floating notes become pinned folio members.

You configure routing (default folio, tags to apply, harvest opt-in) before committing. Every imported logCard carries an idempotency key derived from its source, so re-importing the same archive is a no-op.

Reading it back

Folios and daily notes are reachable through the MCP retrieval tools and, for engine folios, through the agent’s read_folio tool. For how the underlying entity and memory graph is built from this content, see Knowledge graph & memory.