second-brain

# Second Brain

A personal knowledge base for **building understanding that compounds over time**. Not a note dump - a structured system for capturing knowledge you can actually retrieve and use.

## Philosophy

Your second brain should:
- **Capture understanding, not just facts** - Write for your future self who forgot the context
- **Be retrievable** - Structured so you can find things when you need them
- **Stay evergreen** - No private details, credentials, or time-sensitive data
- **Reflect real experience** - Only save what you've actually learned or used

Before saving: *Will future-me thank me for this?*

## Namespace Structure

```
public/                           --> Shareable knowledge
  concepts/                       --> How things work
    [domain]/                     --> Organize by topic
      [concept-name]              --> Individual concepts
  toolbox/                        --> Tools and technologies
    _index                        --> Master index of tools
    [category]/                   --> Group by type
      [tool-name]                 --> Individual tools
  patterns/                       --> Reusable solutions
    [domain]/                     --> Design patterns, workflows
  references/                     --> Quick-reference material
    [topic]/                      --> Cheatsheets, syntax, APIs

private/                          --> Personal only
  notes/                          --> Scratchpad, drafts
  journal/                        --> Dated reflections
```

**Example domains:** `programming`, `devops`, `design`, `business`, `data`, `security`, `productivity`

## Content Formats

### Concepts

For understanding how something works:

```
CONCEPT NAME
============

What it is:
[One-line definition]

Why it matters:
[What problem it solves, when you'd need it]

How it works:
[Explanation with examples]
[ASCII diagrams for architecture/flows where helpful]

+----------+      +----------+
| Client   | ---> | Server   |
+----------+      +----------+

Key insight:
[The "aha" moment - what makes this click]

Related: [links to related concepts]
```

### Toolbox Entries

For tools and technologies you've actually used:

```
TOOL NAME

Category: [category]
Website: [url]
Cost: [free/paid/freemium]

What it does:
[Brief description]

Why I use it:
[Personal experience - what problem it solved for you]

When to reach for it:
[Scenarios where this is the right choice]

Quick start:
[Minimal setup/usage to get going]

Gotchas:
[Things that tripped you up]
```

### Patterns

For reusable solutions:

```
PATTERN NAME

Problem:
[What situation triggers this pattern]

Solution:
[The approach, with code/pseudocode if relevant]

Trade-offs:
[Pros and cons, when NOT to use it]

Example:
[Concrete implementation]
```

### References

For quick-lookup material:

```
REFERENCE: [TOPIC]

[Organized, scannable content]
[Tables, lists, code snippets]
[Minimal prose, maximum signal]
```

## Interaction Rules

### Saving Knowledge

Always confirm before saving:
1. "Want me to save this to your second brain?"
2. Show draft of what will be saved
3. Save after confirmation
4. Confirm what was saved and where

### Retrieving Knowledge

When relevant topics come up:
- Search for existing knowledge
- Surface related concepts
- Connect new learning to existing understanding

### Maintaining Quality

Before saving, verify:
- Written for future self who forgot context
- Includes the WHY, not just the WHAT
- Has concrete examples
- No credentials, API keys, or private paths
- Structured for retrieval

## Anti-Patterns

1. **Don't auto-save** - Always ask first
2. **Don't save unused tools** - Only tools actually used
3. **Don't save half-understood concepts** - Learn first, save after
4. **Don't include secrets** - No API keys, passwords, tokens
5. **Don't create shallow entries** - If you can't explain it well, don't save it
6. **Don't duplicate** - Check if it exists first, update if needed

## API Usage

Use the wrapper script:

```bash
{baseDir}/scripts/ensue-api.sh <method> '<json_args>'
```

### Operations

**Search knowledge:**
```bash
{baseDir}/scripts/ensue-api.sh discover_memories '{"query": "how does X work", "limit": 5}'
```

**List by namespace:**
```bash
{baseDir}/scripts/ensue-api.sh list_keys '{"prefix": "public/concepts/", "limit": 20}'
```

**Get specific entries:**
```bash
{baseDir}/scripts/ensue-api.sh get_memory '{"key_names": ["public/concepts/programming/recursion"]}'
```

**Create entry:**
```bash
{baseDir}/scripts/ensue-api.sh create_memory '{"items":[
  {"key_name":"public/concepts/domain/name","description":"Short description","value":"Full content","embed":true}
]}'
```

**Update entry:**
```bash
{baseDir}/scripts/ensue-api.sh update_memory '{"key_name": "public/toolbox/_index", "value": "Updated content"}'
```

**Delete entry:**
```bash
{baseDir}/scripts/ensue-api.sh delete_memory '{"key_name": "public/notes/old-draft"}'
```

## Toolbox Index

Maintain `public/toolbox/_index` as master reference:

```
TOOLBOX INDEX
=============

Categories:
  languages/      Programming languages
  frameworks/     Libraries and frameworks
  devtools/       Development utilities
  infrastructure/ Deployment, hosting, CI/CD
  productivity/   Workflow and productivity tools
  data/           Databases, analytics, data tools

Recent additions:
  [tool] - [one-line description]

Browse: "show my toolbox" or "what tools do I have for [category]"
```

## Intent Mapping

| User says | Action |
|-----------|--------|
| "save this", "remember this" | Draft entry, confirm, save |
| "what do I know about X" | Search and retrieve relevant entries |
| "add [tool] to toolbox" | Create toolbox entry |
| "list my [domain] concepts" | list_keys for that namespace |
| "show my toolbox" | Show toolbox index |
| "update [entry]" | Fetch, show diff, update |
| "delete [entry]" | Confirm, delete |
| "search for [topic]" | Semantic search across all knowledge |

## Setup

Requires `ENSUE_API_KEY` environment variable.

Get your key at: https://www.ensue-network.ai/dashboard

Configure in clawdbot.json:
```json
"skills": {
  "entries": {
    "second-brain": {
      "apiKey": "your-ensue-api-key"
    }
  }
}
```

## Security

- **NEVER** log or display the API key
- **NEVER** store credentials, tokens, or secrets in entries
- **NEVER** include personal file paths or system details