Introduction
# 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