Skip to content

Projects

Jump to bottom
Rahil Pirani edited this page Sep 21, 2026 · 1 revision

Projects

A project is a named way to group memories around what they are about — a codebase, a client, a personal goal — independent of who can see them or how they were captured. Projects sit alongside tags, workspaces, and source as one more axis for organizing your brain, not a replacement for any of them.

The four-axis model

Every memory can be understood along four independent axes:

  • workspace — who can see it: personal, or a shared company layer.
  • project — what it's about: a named, managed container such as second-brain or client-acme.
  • tags — free-form facets: anything else worth filtering on.
  • source — where it came from: api, claude, notion-sync, and so on.

A project is a thin registry row — a slug, a display name, a description, and a short list of aliases — plus membership on ordinary entries. Membership is just a reserved tag, project:<slug>, so every existing filter, recall, and digest path already understands it: there is no re-indexing and no separate storage for project membership. A memory can belong to more than one project, the same way it can carry more than one tag.

Creating a project

From the dashboard

Open the Projects page and choose New project. Enter a name; the slug previews live as you type (lowercase, spaces become hyphens, everything else stripped). Add an optional description, then save. See Web UI → Projects.

Automatically, from an agent

You do not have to create a project ahead of time for an agent to use it. When remember or POST /capture is called with a project that doesn't exist yet, Second Brain creates it silently — a registry row with the slug as both id and name, active status, and nothing else filled in. The capture is never blocked or slowed down waiting on this. You can rename it or add a description from the dashboard afterward.

This only happens on writes. recall, list_recent, and the other read paths return an "unknown project" error instead of guessing, listing the active projects you do have access to so you can correct a typo rather than silently searching nothing.

Passing a raw project:<slug> tag directly, instead of the project parameter, attaches an entry to that project without creating the registry row — useful for scripting, but it means the project won't show up on the Projects page until something creates it properly.

Aliases: adopting memories you already have

Projects are new, but your tags aren't. If you've been tagging things signpath for months before the Projects page existed, you don't need to go back and retag every one of those memories. Instead, create the project and add signpath as an alias:

  1. Create a project named "SignPath" — it gets the slug signpath.
  2. Open its detail page and add signpath under Aliases.
  3. The project's memory list, digest, and counts now include every entry tagged signpath, exactly as if each one carried project:signpath.

An alias is a plain topic tag the project claims — up to 16 per project. No row is rewritten and no entry is retagged; the project simply widens its membership query to include the alias at read time. This is also why deleting a project and later re-creating it re-adopts the same memories: the underlying tags never moved.

One distinction worth keeping in mind: a project's memory count shown in the dashboard reflects only entries explicitly carrying project:<slug>. Alias-matched entries are included in what you see and search under the project, but not in that number.

Archiving and deleting a project

Archive hides a project from pickers, from list_projects, and from the nightly digest rotation, without touching anything else. Its memories are untouched, reads that name it directly still work, and its Prompt Capsule (if it has one) still serves. Archiving is for projects that are finished, not projects you want to erase.

Delete removes only the registry row — the slug, name, description, and alias list. It does not touch any memory:

Memories are kept; only the project grouping is removed.

Every entry keeps its project:<slug> tag (hidden from the tag chips in the UI as reserved, same as before you deleted anything). If you create a new project with the same slug later, it immediately re-adopts every one of those entries — deleting a project is reversible in that sense, even though the registry row itself is gone for good.

Nightly digests

Active projects get the same nightly compression treatment as high-volume tags, riding the existing overnight rotation rather than a separate schedule. Each night, for the workspace whose turn it is, Second Brain looks at active projects alongside the usual frequency-driven topic tags and, for any project with enough eligible entries, synthesizes a digest — a single condensed entry describing the current state of that project, tagged synthesized and project:<slug> so it lands back inside the project it summarizes. The same protections apply as any other digest: memories that are important, recently useful, or have survived a contradiction are kept whole rather than folded away. See How It Works → Semantic compression for the underlying rules, and API Reference → GET /digest to trigger one on demand for a specific project.

Prompt Capsules and projects

Prompt Capsules already supported a project scope — capsule:project:<id> — before the Projects page existed, using an opaque id the caller invented. That id namespace and the project slug namespace are now the same: a capsule project id that matches a registered project's slug is simply that project's capsule. Capsule ids that don't match any registered project keep working exactly as before — nothing you built against get_prompt_capsule or GET /prompt-capsules/projects/<id> breaks.

In practice this means you can create the project first — so it shows up on the Projects page, has a description, and can be browsed and digested — and then use its slug as the capsule id, instead of the two living as unrelated ids that happen to share a name. See the Prompt Capsules section of the README for the full capsule mechanics.

Using projects as an agent

Agents discover projects with the list_projects MCP tool, which returns each active project's slug, name, workspace, and the first line of its description (pass include_archived to also see archived ones). Once you know the slug, pass it as project on remember, recall, and list_recent — the same way you'd pass workspace to pick a layer.

Prefer project over a bare topic tag when a conversation is clearly about a known project: it groups the memory with everything else about that project, including its digest and capsule, in a way a plain tag doesn't. remember auto-creates an unknown project rather than failing; recall and list_recent return the near-miss error described above so you can correct a typo instead of quietly searching nothing.

See also

Clone this wiki locally