Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

12.9 KB
Raw Blame
---
id: second-brain
title: Second Brain
---

Mercury has a persistent, structured memory that grows with every conversation. When enabled, it learns what is true about you — and how you like to work — as beliefs with evidence, retrieves what is relevant to each message, and tells you when it learned something that changes how it behaves.

## Reading past conversations

Saved conversations and extracted memories are different. Ask Mercury to find a previous chat or check what you said: `search_sessions` searches saved titles and dialogue, and `read_session` reads a matching transcript with its date and message references. This works even when Second Brain is disabled or the detail was never extracted into a memory. It reads the same canonical sessions shown in web and desktop chat history, including conversations imported by the existing legacy migration.

Recall is available in owner CLI, web, desktop and internal turns, or remote channels that supply an explicit admin role. Channel members, remote callers without a verified role, general-access chats and workers whose tool allowlist excludes recall cannot use it. Archived chats require an explicit request; deleted sessions are never returned. Reasoning, tool traces, permission prompts and internal metadata are omitted.

Results are paginated and limited to 16,000 serialized characters per call. Search scans at most 100 sessions and 32 MiB per call; individual transcript files over 8 MiB are reported as unavailable. Mercury must follow the returned offset/cursor for more results and disclose skipped records. Read cursors expire if the session changes. There is no new index, background job or model call for retrieval. Clearing a Second Brain belief does not erase its original conversation; delete that conversation separately if you want its transcript removed.

## The Owner Model: beliefs, not just facts

Since 1.4.1 Mercury holds **beliefs** about you rather than a pile of facts. A belief is a claim ("prefers one command over many manual steps") with evidence for and against it, a confidence that fades unless it is seen again, the context it applies in (everywhere, one project, one channel, one domain), and a status: **candidate** (seen once) → **held** (seen in two sessions) → **confirmed** (you said so). Two beliefs that cannot both be true are **contested** and Mercury asks you once. What you state outright never fades; what Mercury inferred does, unless it keeps being true.

What it learns are *working traits* that change how Mercury behaves: reply length, when to ask before acting (per project or domain), options vs a recommendation, tone, your expertise and risk appetite per domain, when you are usually around, and how you give feedback. It never infers personality types, health, religion, politics or sexuality, never stores passwords or keys, and never generalises about other people beyond what you said.

**How it learns.** After each turn, a small model call turns the turn into belief operations — or nothing, which is the usual outcome. Mercury's own replies are never evidence about you. Every hour of activity (and at shutdown) a reflection pass reads your messages across sessions, infers traits, merges duplicates, flags contradictions and rewrites the owner brief. The brief — *About you* and *How to work with you* — is in every prompt, together with the beliefs relevant to the current message.

**What you see.** When something behaviour-changing is learned, the reply ends with one line: `☿ Noted: you'd rather I just run things here without asking. Say "forget that" to undo.` From any chat:

| Command | What it does |
|---|---|
| `/memory learned [days]` | What Mercury learned recently, numbered |
| `/memory beliefs` | Traits by dimension, then confirmed preferences |
| `/memory contested` | Pairs Mercury can't settle; `/memory settle <n> a\|b` |
| `/memory confirm <n>` · `/memory forget <n>` · `/memory correct <n> <what is true>` | Act on a numbered item |
| `/forget <text>` · "forget that" | Forget the best match, or the last `☿ Noted` line |

`~/.mercury/soul/owner.md` holds the same brief in plain text; anything you write under **My notes** is read back as something you stated. The dashboard's Memory page shows what was learned with Confirm / Forget, and a **Quarantined** list: rows the old extractor saved by mistake (Mercury's own replies stored as your preferences), hidden but restorable.

## How it works

1. **Extraction** — After each turn, a strict extractor turns what you said and did into belief operations: create, support, contradict, or nothing at all. Mercury's own replies are never evidence about you.
2. **Retrieval** — Before each message, up to 5 beliefs relevant to it (with their confidence and context) go into the prompt, and the "About you" / "How to work with you" brief sits in every prompt.
3. **Reflection** — After every hour of activity and at shutdown, one model pass reads your messages across sessions: it infers working traits, merges duplicates, flags contradictions, rewrites the brief, and lets faded beliefs retire.
4. **Decay** — Confidence fades per kind (a fact over a year, a preference over months, a trait over weeks) unless the belief is seen again; what you stated outright never fades. A belief retires only when it faded *and* was contradicted or went stale for two half-lives.

**One source.** Every view of your memory — `/memory`, the dashboard, the `search_memory` and `save_memory` tools, the bots, cloud sync — reads and writes the same belief store. Who you are (your name, email, handles) lives in `identity.owner` in `mercury.yaml`, the one place it is set; Mercury never stores it as a belief.

**Upgrading from an older Mercury.** The first boot after the upgrade copies `second-brain.db` to `second-brain.pre-owner-model.db` next to it, then moves your memories into beliefs: real ones become candidates (or held, when they had been seen more than once); rows that were Mercury's own replies, credentials or templated filler are quarantined, never deleted, and wait in the dashboard under *Quarantined* with a Restore button. Nothing you could see before disappears, `/memory` and the dashboard keep working, and a reflection pass two minutes after that boot judges the migrated candidates against your real sessions.

## Memory Tiers

Mercury models memory in two tiers, mirroring how human memory works:

| Tier | Scope values | Behavior |
|------|--------------|----------|
| **Conscious** | `durable`, `active` | Always available for retrieval. Top-of-mind. |
| **Subconscious** | `subconscious` | Out of active recall. Confidence does **not** decay here. Recalled automatically when relevant to the current conversation. |

### Subconscious mechanics

- After **30 days** without being referenced, an active memory is moved to the subconscious instead of being deleted.
- Subconscious memories are preserved with their original confidence — no further decay applies while they sit there.
- During retrieval, if conscious results are weak, Mercury also searches the subconscious and surfaces the strongest matches. When a subconscious memory is recalled into a relevant conversation, it is **promoted back to the conscious tier**.
- Subconscious memories are only hard-deleted if explicitly dismissed. Otherwise they remain available forever.

This is why Mercury can resurface "I told you that two years ago" facts without polluting day-to-day reasoning.

## Memory Types

| Type | Default scope | What it stores |
|------|---------------|---------------|
| `identity` | durable | Who you are — name, role, background |
| `preference` | durable | What you like and dislike |
| `goal` | active | What you're working toward |
| `project` | active | What you're building |
| `habit` | durable | Behavioral patterns and routines |
| `decision` | active | Decisions and choices you've made |
| `constraint` | durable | Rules and constraints you follow |
| `relationship` | durable | People and connections |
| `episode` | active | Specific events and experiences |
| `reflection` | durable | System-generated insights from patterns |

## Conflict Resolution

When Mercury detects opposing memories (e.g. "prefers TypeScript" vs "prefers Python"), the higher-confidence one wins. If equal, the newer one wins. Negation mismatches ("likes X" vs "does not like X") are detected and resolved automatically.

## Evidence Kinds

- **direct** — Explicitly stated by you (highest confidence)
- **inferred** — Pattern Mercury detected (decays over time)
- **manual** — Added via `/memory` command or the web UI
- **system** — Auto-generated reflections from consolidation

## Web Dashboard Views

The Second Brain is exposed through four interconnected pages in the web dashboard.

### Memory (`/second-brain/memory`)

A full browser for every memory item.

- **Scope filter** — toggle between `conscious` and `subconscious` views. A 💤 badge marks subconscious entries.
- **Search** — full-text search across memory summaries; results merge conscious and subconscious matches.
- **Inline edit** — change summary, type, importance, confidence, or scope.
- **Add memory** — manually create a memory with type, summary, and evidence.
- **Delete** — soft-dismiss a memory (only explicit dismissal hard-deletes; otherwise items just move to subconscious).

### Persons (`/second-brain/persons`, `/second-brain/persons/:id`)

People Mercury has encountered are extracted into a structured table.

- The listing shows each person's name, last-seen timestamp, and the number of memories associated with them.
- Click a person to open their detail page with their facts, related memories, and links to other persons (via `relationship` memories).

### Goals (`/second-brain/goals`)

A tabbed view that filters memories by type:

- **Goals tab** — every memory with `type: goal`
- **Projects tab** — every memory with `type: project`

You can add new goals/projects directly from this page — they are stored as standard memories so the agent can reason over them.

### Graph (`/second-brain/graph`)

A force-directed graph visualization that draws nodes for memories, persons, and goals, and edges for their relationships. Useful for spotting clusters (e.g. all goals connected to a particular project, or all persons connected to a company).

## Managing Memory from chat channels

Use `/memory` in any channel:

| Action | CLI | Telegram |
|--------|-----|----------|
| Overview | Arrow-key menu → Overview | Inline button: 📋 Overview |
| Recent memories | Arrow-key menu → Recent | Inline button: 🔍 Recent |
| Subconscious | Arrow-key menu → Subconscious | Inline button: 💤 Subconscious |
| Search | Arrow-key menu → Search | Not available (ask Mercury to search) |
| Pause learning | Arrow-key menu → Pause | Inline button: ⏸ Pause |
| Resume learning | Arrow-key menu → Resume | Inline button: ▶ Resume |
| Clear all | Arrow-key menu → Clear (with confirmation) | Inline button: 🗑 Clear → Yes |

## API Endpoints

The web dashboard talks to the brain through a small REST surface:

```
GET    /api/brain/status
GET    /api/brain/memory                 # ?scope=conscious|subconscious
GET    /api/brain/memory/search?q=...
GET    /api/brain/memory/:id
PUT    /api/brain/memory/:id
DELETE /api/brain/memory/:id
POST   /api/brain/memory                 # manual add
GET    /api/brain/persons
GET    /api/brain/persons/:id
GET    /api/brain/persons/:id/memories
GET    /api/brain/graph
```

Goals and projects are not a separate resource — they are memories filtered by `type=goal` or `type=project` against `/api/brain/memory`.

## Which model learns

Extraction and reflection are strict-JSON jobs; a weak free-tier model misses most of what you say or returns nothing. Point them at a capable provider without changing your chat model:

```yaml
memory:
  learning:
    provider: anthropic   # any name from `providers`; falls back to the default when unusable
```

(`LEARNING_PROVIDER=anthropic` does the same.) A Haiku-class model is plenty; each turn costs one small call and each hour of activity one reflection.

## Enable / Disable

Second Brain is **enabled by default**. To disable it:

- Environment variable: `SECOND_BRAIN_ENABLED=false`
- Config file: set `memory.secondBrain.enabled: false` in `~/.mercury/mercury.yaml`

When disabled, Mercury falls back to basic long-term fact search (JSONL, text-match only). No extraction, no consolidation, no SQLite.

All data is stored locally in `~/.mercury/memory/second-brain/second-brain.db` (SQLite). Nothing leaves your machine.

## Troubleshooting

### Native module version mismatch

If you see `NODE_MODULE_VERSION` mismatch errors in logs, the `better-sqlite3` native addon was compiled against a different Node.js version than your runtime. Fix with:

```bash
npm rebuild better-sqlite3
```

When `better-sqlite3` fails to load, Second Brain silently falls back to disabled — memory extraction and consolidation will not run. Check daemon logs (`mercury logs`) for SQLite-related errors if memories aren't being stored.