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.

feat: implement persistent Second Brain system with automatic fact extraction, consolidation, and SQLite storage

Salman Qureshi09de5b280bdb
diff --git a/README.md b/README.md
index 70794358..a0a789cb 100644
--- a/README.md
+++ b/README.md
@@ -185,15 +185,18 @@ CLI commands: `mercury telegram list|approve|reject|remove|promote|demote|reset`
## Second Brain
-Mercury builds a structured memory of facts about you, your preferences, and your project context — stored locally in SQLite with full-text search.
-
-- **10 memory types** — preferences, relationships, project facts, decisions, routines, and more
-- **Automatic extraction** — after each conversation, Mercury pulls important facts and stores them
-- **Relevant recall** — only memories matching the current context are injected into the system prompt
-- **User controls** — `/memory` to view, search, and manage stored facts
-- **Auto-pruning** — stale entries are expired after 7 days of inactivity
-
-All memory stays on your machine in `~/.mercury/memory/second-brain.db`.
+Mercury builds a structured, persistent memory that grows with every conversation. Enabled by default, it automatically extracts, stores, and recalls facts about you.
+
+- **10 memory types** — identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection
+- **Automatic extraction** — after each conversation, Mercury pulls 0–3 facts with confidence, importance, and durability scores
+- **Relevant recall** — before each message, the top 5 matching memories (900-char budget) are injected into context
+- **Auto-consolidation** — every 60 min, Mercury builds a profile summary, active-state summary, and generates reflections from patterns
+- **Conflict resolution** — opposing memories are resolved by confidence (higher wins) or recency (newer wins)
+- **Auto-pruning** — active-scope memories stale after 21 days; inferred memories decay; low-confidence durable memories dismissed after 120 days
+- **User controls** — `/memory` for overview, search, pause, resume, and clear
+- **Disable** — `SECOND_BRAIN_ENABLED=false` env var or `memory.secondBrain.enabled: false` in config
+
+All data stays on your machine in `~/.mercury/memory/second-brain/second-brain.db` (SQLite + FTS5).
## Configuration
diff --git a/docs/docs.html b/docs/docs.html
index 73e881bc..aafbc9e6 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -319,6 +319,7 @@
<a href="#tools">Built-in Tools</a>
<a href="#configuration">Configuration</a>
<a href="#permissions">Permissions</a>
+ <a href="#second-brain">Second Brain</a>
<a href="#providers">Provider Fallback</a>
<a href="#scheduling">Scheduling</a>
<a href="#skills">Skills</a>
@@ -1380,6 +1381,72 @@
<p>On <strong>Telegram</strong>: inline keyboard buttons appear with the first message. Use <code>/permissions</code> to change mode at any time.</p>
<p><strong>Scheduled tasks</strong> always run in Allow All mode — filesystem access and shell commands are auto-approved. You receive a notification before each task executes.</p>
+ <h2 id="second-brain">Second Brain</h2>
+ <p>Mercury has a persistent, structured memory that grows with every conversation. When enabled, it automatically extracts, stores, and retrieves facts about you — your preferences, goals, projects, habits, and more.</p>
+
+ <h3>How it works</h3>
+ <ol>
+ <li><strong>Extraction</strong> — After each conversation, Mercury pulls 0&ndash;3 facts and stores them with type, confidence, importance, and durability scores.</li>
+ <li><strong>Retrieval</strong> — Before each message, the top 5 relevant memories (within a 900-char budget) are injected into context. Mercury references them naturally.</li>
+ <li><strong>Consolidation</strong> — Every 60 minutes, Mercury builds a profile summary, an active-state summary, and generates <code>reflection</code> memories from detected patterns.</li>
+ <li><strong>Pruning</strong> — Active-scope memories stale after 21 days. Inferred memories decay. Low-confidence durable memories are dismissed after 120 days. Memories reinforced 3+ times are promoted to durable.</li>
+ </ol>
+
+ <h3>Memory Types</h3>
+ <table class="cmd-table">
+ <thead>
+ <tr><th>Type</th><th>Scope</th><th>What it stores</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>identity</td><td>durable</td><td>Who you are — name, role, background</td></tr>
+ <tr><td>preference</td><td>durable</td><td>What you like and dislike</td></tr>
+ <tr><td>goal</td><td>active</td><td>What you're working toward</td></tr>
+ <tr><td>project</td><td>active</td><td>What you're building</td></tr>
+ <tr><td>habit</td><td>durable</td><td>Behavioral patterns and routines</td></tr>
+ <tr><td>decision</td><td>active</td><td>Decisions and choices you've made</td></tr>
+ <tr><td>constraint</td><td>durable</td><td>Rules and constraints you follow</td></tr>
+ <tr><td>relationship</td><td>durable</td><td>People and connections</td></tr>
+ <tr><td>episode</td><td>active</td><td>Specific events and experiences</td></tr>
+ <tr><td>reflection</td><td>durable</td><td>System-generated insights from patterns</td></tr>
+ </tbody>
+ </table>
+
+ <h3>Conflict Resolution</h3>
+ <p>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.</p>
+
+ <h3>Evidence Kinds</h3>
+ <ul>
+ <li><strong>direct</strong> — Explicitly stated by you (highest confidence)</li>
+ <li><strong>inferred</strong> — Pattern Mercury detected (decays over time)</li>
+ <li><strong>manual</strong> — Added via <code>/memory</code> command</li>
+ <li><strong>system</strong> — Auto-generated reflections from consolidation</li>
+ </ul>
+
+ <h3>Managing Memory</h3>
+ <p>Use <code>/memory</code> in any channel:</p>
+ <table class="cmd-table">
+ <thead>
+ <tr><th>Action</th><th>CLI</th><th>Telegram</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>Overview</td><td>Arrow-key menu → Overview</td><td>Inline button: 📋 Overview</td></tr>
+ <tr><td>Recent memories</td><td>Arrow-key menu → Recent</td><td>Inline button: 🔍 Recent</td></tr>
+ <tr><td>Search</td><td>Arrow-key menu → Search</td><td>Not available (ask Mercury to search)</td></tr>
+ <tr><td>Pause learning</td><td>Arrow-key menu → Pause</td><td>Inline button: ⏸ Pause</td></tr>
+ <tr><td>Resume learning</td><td>Arrow-key menu → Resume</td><td>Inline button: ▶ Resume</td></tr>
+ <tr><td>Clear all</td><td>Arrow-key menu → Clear (with confirmation)</td><td>Inline button: 🗑 Clear → Yes</td></tr>
+ </tbody>
+ </table>
+
+ <h3>Enable / Disable</h3>
+ <p>Second Brain is <strong>enabled by default</strong>. To disable it:</p>
+ <ul>
+ <li>Environment variable: <code>SECOND_BRAIN_ENABLED=false</code></li>
+ <li>Config file: set <code>memory.secondBrain.enabled: false</code> in <code>~/.mercury/mercury.yaml</code></li>
+ </ul>
+ <p>When disabled, Mercury falls back to basic long-term fact search (JSONL, text-match only). No extraction, no consolidation, no SQLite.</p>
+ <p>All data is stored locally in <code>~/.mercury/memory/second-brain/second-brain.db</code> (SQLite). Nothing leaves your machine.</p>
+
<h2 id="providers">Provider Fallback</h2>
<p>Configure multiple LLM providers. Mercury tries them in order and falls back automatically. When a provider
fails, Mercury tries the next one and remembers the last successful provider.</p>
diff --git a/docs/index.html b/docs/index.html
index ec4ce1e0..2fdf98a7 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -163,12 +163,48 @@
<div class="feature-icon">🛡</div>
<h3>Permission Hardened</h3>
<p>Folder-level read/write scoping. Command blocklist (sudo, rm -rf, etc. — never executed). Pending approval
- flow. Skill elevation with granular allowed-tools. No surprises.</p>
+ flow. Ask Me or Allow All mode per session.</p>
</div>
</div>
</div>
</section>
+ <section id="second-brain" class="section section-alt">
+ <div class="container">
+ <h2 class="section-title">🧠 Second Brain</h2>
+ <p class="section-subtitle">Mercury doesn't just chat — it <em>remembers</em>. A persistent, structured memory that grows with every conversation.</p>
+ <div class="brain-grid">
+ <div class="brain-card" data-reveal>
+ <h3>Learns Automatically</h3>
+ <p>After each conversation, Mercury extracts facts about you — your preferences, goals, projects, habits, relationships, and decisions. No manual entry needed.</p>
+ </div>
+ <div class="brain-card" data-reveal>
+ <h3>Recalls What Matters</h3>
+ <p>Only memories relevant to the current conversation are injected — up to 5 facts within a 900-character budget. Your context window stays clean.</p>
+ </div>
+ <div class="brain-card" data-reveal>
+ <h3>Resolves Conflicts</h3>
+ <p>Preferences change. When Mercury detects a contradiction (you liked X, now you prefer Y), the higher-confidence memory wins. No stale data.</p>
+ </div>
+ <div class="brain-card" data-reveal>
+ <h3>10 Memory Types</h3>
+ <p>Identity, preference, goal, project, habit, decision, constraint, relationship, episode, and reflection — each scored by confidence, importance, and durability.</p>
+ </div>
+ <div class="brain-card" data-reveal>
+ <h3>Auto-Consolidation</h3>
+ <p>Every hour Mercury synthesizes a profile summary and generates reflections from patterns it detects. Active memories promote to durable when reinforced 3+ times.</p>
+ </div>
+ <div class="brain-card" data-reveal>
+ <h3>You Stay in Control</h3>
+ <p><code>/memory</code> gives you overview, search, pause, and clear. Second Brain can be disabled entirely via config. All data stays on your machine in SQLite.</p>
+ </div>
+ </div>
+ <div class="brain-note" data-reveal>
+ <p>Enable/disable: <code>SECOND_BRAIN_ENABLED=false</code> env var or <code>memory.secondBrain.enabled: false</code> in <code>~/.mercury/mercury.yaml</code>. Enabled by default.</p>
+ </div>
+ </div>
+ </section>
+
<section id="how-it-works" class="section section-dark">
<div class="container">
<h2 class="section-title">Up and Running in 60 Seconds</h2>
diff --git a/docs/style.css b/docs/style.css
index 0855b031..fe882864 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -603,4 +603,25 @@ footer {
.search-overlay { padding-top: 8vh; }
.search-modal { margin: 0 12px; max-width: none; }
.search-footer { display: none; }
-}
\ No newline at end of file
+}
+
+/* ── Second Brain ── */
+.section-alt { background: #0c0c14; }
+.brain-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+ gap: 24px;
+ margin-top: 48px;
+}
+.brain-card {
+ background: var(--bg-card);
+ border: 1px solid var(--border);
+ border-radius: 12px;
+ padding: 28px 24px;
+ transition: all 0.3s ease;
+}
+.brain-card:hover { background: var(--bg-card-hover); border-color: var(--cyan-dim); transform: translateY(-2px); }
+.brain-card h3 { font-size: 1.15em; margin-bottom: 8px; color: var(--white); }
+.brain-card p { color: var(--gray); font-size: 0.95em; line-height: 1.65; }
+.brain-note { margin-top: 32px; text-align: center; color: var(--gray-dim); font-size: 0.88em; }
+.brain-note code { background: var(--bg-card); border: 1px solid var(--border); padding: 2px 6px; border-radius: 4px; font-size: 0.85em; color: var(--cyan); }
\ No newline at end of file
diff --git a/src/core/agent.ts b/src/core/agent.ts
index 18d6e443..98c1c659 100644
--- a/src/core/agent.ts
+++ b/src/core/agent.ts
@@ -723,6 +723,19 @@ export class Agent {
prompt += `\n\nEnvironment:\n- Platform: ${process.platform}\n- Working directory: ${this.capabilities.getCwd()}`;
+ if (this.userMemory) {
+ const summary = this.userMemory.getSummary();
+ prompt += `\n\nSecond Brain is ENABLED. You have a persistent, structured memory of ${summary.total} facts about this user.`;
+ prompt += `\nMemory types: identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection.`;
+ prompt += `\nRelevant memories are automatically injected before each message. You can reference them naturally (e.g. "I remember you prefer TypeScript").`;
+ prompt += `\nUsers can manage memory with: /memory (overview, search, pause learning, clear).`;
+ if (summary.learningPaused) {
+ prompt += `\nLearning is currently PAUSED — no new memories will be extracted from conversations until resumed.`;
+ }
+ } else {
+ prompt += '\n\nSecond Brain is DISABLED. Basic long-term memory (text search over facts) is still active.';
+ }
+
const toolNames = this.capabilities.getToolNames();
const githubTools = ['create_pr', 'review_pr', 'list_issues', 'create_issue', 'github_api'];
const hasGitHub = githubTools.some(t => toolNames.includes(t));