Second Brain Core

Second Brain Core

Universal Memory Layer for AI Systems & Autonomous Developers
Models are temporary. Memory is permanent.

---

⚡ Overview

Second Brain Core is the local-first cognitive substrate and universal memory layer for AI models and autonomous developer agents. It allows any LLM (Claude, Gemini, GPT, Copilot, Codex, Cursor) to seamlessly pause, switch, and resume complex engineering work without re-explaining context, losing architectural decisions, or replaying massive conversation histories.

Instead of storing raw ephemeral chat logs, Second Brain stores structured decisions, goals, tasks, relationships, and checkpoints inside a high-performance graph and event-sourced persistence architecture.

🌐 Official Website & Docs: vjnaveen2005.github.io/second-brain-core or view locally via brain 3d at http://127.0.0.1:3000/website.

---

🧠 How It Works & Architecture

Second Brain operates on a continuous Cognitive State Loop:

flowchart TD
    User["👤 Developer / User"] -->|Starts New Session| Agent["🤖 AI Agent (Claude / Cursor / Gemini)"]
    Agent -->|1. Reads Active State| WorkingMem["⚡ Working Memory (<= 1000 tokens)"]
    WorkingMem -->|Project, Current Task, Decisions| Agent
    Agent -->|2. Executes & Makes Technical Choices| BrainAPI["🧠 Second Brain Core Engine"]
    BrainAPI -->|3. Records Important Choices| HotMem["🔥 Hot / Warm Memory (Decisions & Graph)"]
    Agent -->|4. Checkpoint on Exit / Milestone| ColdMem["❄️ Checkpoint Snapshot (Immutable Event Log)"]
    ColdMem -->|Restores Next Day Across Any Model| WorkingMem

🏗️ 4-Tier Memory Hierarchy

[ User Profile: Naveen (Founder / CEO) ]
        │
        │ OWNS
        ▼
[ Workspace: Production / Personal ]
        │
        │ CONTAINS
        ▼
[ Project: Second Brain Core ]
        │
        ├─► [ Tier 1: Working Memory ] (<= 1000 tokens - Immediate active task & next step)
        ├─► [ Tier 2: Hot Memory ]     (Active sprint milestones & architectural decisions)
        ├─► [ Tier 3: Warm Memory ]    (Past technical research, benchmarks, tech stack indices)
        └─► [ Tier 4: Cold Memory ]    (Archived checkpoints, logs, and historical snapshots)

---

📋 Universal AI Agent Skill (Copy & Paste Prompt)

Second Brain includes a specialized Agent Skill (skills/second-brain/SKILL.md) that turns any AI assistant into a memory-aware autonomous partner.

🚀 Copy & Paste Setup Prompt for Your AI Agent:

Copy this single prompt and give it to any AI agent (Cursor, Claude, Antigravity, Gemini, ChatGPT). It will automatically install Second Brain, create the skill file, and resume your work:

<!-- SECOND BRAIN CORE AUTO-SETUP & AGENT SKILL -->
You are my autonomous AI developer. Integrate Second Brain Core for persistent memory across all sessions:

1. INSTALL SECOND BRAIN:
   Run: `npm install -g second-brain-core` (or verify it is installed with `brain status`).

2. CREATE THE AGENT SKILL:
   Create a skill file (in `.cursorrules`, `.claude/skills/second-brain/SKILL.md`, or your agent's skill directory):
   ```markdown
   ---
   name: second-brain
   description: Universal persistent memory layer for AI agents. Loads project state at start and checkpoints before exit.
   ---
   # Second Brain Memory Protocol
   - AT SESSION START: Always execute `brain status` (or use MCP `brain_status`) to load active project, current progress, next task, and architectural decisions.
   - DURING WORK: Never contradict previous decisions. When important technical choices are made, run `brain remember "<decision>" --tags architecture`.
   - AT SESSION END: When we finish or pause, create a checkpoint:
     `brain checkpoint "<summary>" --next "<next task>" --progress <0-100>`.
   - FOUNDER PROFILE: Run `brain identity show` to load profile & CEO reasoning mode.

3. INITIALIZE NOW: Run brain status right now and report back with my active project, progress, and immediate next task to resume work!

### 📂 About the `skills/` Directory:
- [`skills/second-brain/SKILL.md`](./skills/second-brain/SKILL.md): Complete protocol definition that specifies how agents initialize sessions, detect blockers, respect user persona modes (`CEO`, `ENGINEER`, `CREATIVE`, `SCIENTIST`), and serialize checkpoints.

---

## 💎 Key Features

- **🌐 100% Local-First Storage:** Runs completely offline on your machine (`~/.second-brain/`) with zero cloud lock-in and zero Docker prerequisites.
- **🌌 3D Interactive Cognitive Universe:** A visual 3D WebGL Force Graph running in real-time (`brain 3d`) with node inspection and instant search.
- **🧠 Identity & CEO Executive Mode:** Remembers who you are (Naveen / Founder), your companies, YouTube channels, coding standards, and prioritizes strategic ROI when in `CEO` mode.
- **🔄 Universal Cross-Model Continuation:** One-click resume prompts formatted specifically for Claude (XML), Gemini (Structured Markdown), GPT (System/User frames), and Copilot.
- **🔌 Model Context Protocol (MCP) Server:** Native `stdio` MCP server allowing Cursor, Claude Desktop, Antigravity, or Cline to autonomously query and write to Second Brain.
- **🌲 Semantic Knowledge Graph:** Automatically interlinks Workspaces, Projects, Goals, Decisions, Checkpoints, and Memories into an interconnected knowledge web.

---

## 🚀 Quick Start

### 1. Installation

#### Via NPM (Global CLI):
```bash
npm install -g second-brain-core

Or from Source:

git clone https://github.com/VJNAVEEN2005/second-brain-core.git
cd second-brain-core
npm install
npm run build
npm link

2. CLI Usage (brain)

You can now use the global brain CLI from any terminal or directory on your computer:

# Check current cognitive state
brain status

# Launch the interactive 3D WebGL Cognitive Universe in browser
brain 3d

# Generate instant resume prompt for any model
brain resume Gemini
brain resume Claude
brain resume GPT

# Manage Identity & CEO Mode
brain identity show
brain mode CEO
brain mode ARCHITECT
brain mode CODER

# Create a checkpoint
brain checkpoint "Finished 3D WebGL graph and official logo integration" --progress 95

# View recent event timeline
brain log

3. Model Context Protocol (MCP) Setup

Add Second Brain Core to your Claude Desktop, Cursor, or any MCP-compatible agent configuration:

Option A: Run directly via NPX (Recommended for users)

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "second-brain-core", "mcp"]
    }
  }
}

Option B: Local Development / Clone

{
  "mcpServers": {
    "second-brain": {
      "command": "node",
      "args": ["dist/cli/index.js", "mcp"]
    }
  }
}

Now any AI agent can autonomously invoke:

• brain_status: Inspect active project, goal, and working memory.
• brain_checkpoint: Snapshot engineering progress before context limits.
• brain_resume: Pull resume instructions when starting a new session.
• brain_remember: Store long-term knowledge, decisions, or user preferences.
• brain_recall: Query the 4-tier memory by semantic tags or query.

---

🔍 Why Second Brain Core vs. Alternatives?

Feature	Second Brain Core	Mem0	LangChain Memory	Letta (MemGPT)
Primary Architecture	Graph + Event-Sourced Checkpoints	Vector Database	Ephemeral Buffer / KV	State Machine Agent
Model Agnostic Switch	✅ Resume across Claude/GPT/Gemini	⚠️ Requires API Key/Cloud	❌ Locked to session/chain	❌ Requires custom agent runtime
Model Context Protocol (MCP)	✅ Native Native 1st-Class Support	⚠️ Community wrapper	❌ No	⚠️ Partial
100% Local-First & Zero Leakage	✅ Local SQLite / Filesystem	❌ Cloud / External Vector DB	✅ In-memory	⚠️ Postgres / Docker Server
Context Window Consumption	⚡ Micro-context (≤ 1000 tokens)	⚠️ Variable vector chunks	❌ Huge conversation replay	⚠️ Large context overhead
Decision & Architecture Lineage	✅ Explicit graph tracking	❌ Unstructured text chunks	❌ None	❌ State prompt only

---

📦 NPM Package Publishing Workflow

To publish updates to the NPM Package Registry:

# 1. Login to npm (opens browser authentication)
npm login

# 2. Build the project
npm run build

# 3. Publish to npm
npm publish --access public

---

🧪 Testing & Verification

Run the comprehensive test suite (43 unit & integration tests):

npm test

---

📋 Master Specification

Refer to SECOND_BRAIN_MASTER_SPEC.md for the complete design contract, data schemas, SDK API specification, and architectural blueprint.

---

Built with ❤️ for AI Engineers and Autonomous Builders