# Second Brain > Use a local Markdown second-brain repository for persistent, auditable memory. Use when Codex needs prior context, user preferences, project history, decisions, research notes, references, meeting/session summaries, task briefs, governance state, bootstrap status, encryption/sync status, or durable knowledge outside the current conversation; also use when asked to add, update, search, organize, audit, bootstrap, synchronize, encrypt, decrypt, capture, synthesize, or summarize second-brain memory from a repository derived from second-brain-template. - Skill: `marcelorusso/second-brain` (Agent Skill) - Install (CLI): `npx skillmds@latest add marcelorusso/second-brain` - Raw SKILL.md: https://api.skillmd.com/api/skills/marcelorusso/second-brain/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: marcelorusso (https://skillmd.com/u/marcelorusso) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/marcelorusso/second-brain --- # Second Brain ## Core Rule Use a second-brain repository as an external, file-first memory layer. Do not assume a personal path, account name, operating system, or clone name. Resolve the active brain root in this order: 1. The current workspace, when it contains `tools/memory.ps1` and the second-brain layout. 2. `SECOND_BRAIN_HOME`, when set and valid. 3. The registered MCP server named `second-brain`, when available. 4. An explicit path supplied by the user. 5. A likely local clone such as `$HOME/second-brain` or `$HOME\second-brain`, only after checking that it exists. Prefer MCP tools when available and healthy. Use the bundled CLI when MCP is unavailable, stale, missing a tool, or when direct validation is clearer. Use direct Markdown reads for inspection. Prefer MCP/CLI for writes because they preserve metadata conventions and rebuild the SQLite index. `delete` is recoverable: it moves entries to `.trash/`. ## Template vs Daily-Use Before substantive work, determine the repository mode from Git remotes and local instructions: - Template repository: the remote repository name ends with `-template`. Do not treat startup sync as an operational requirement. The template stores workflows, hooks, bootstrap logic, encryption artifacts, docs, and rules for derived repositories. - Daily-use repository: the remote repository name does not end with `-template`. Run startup sync before substantive work unless the user explicitly says not to. ```powershell \tools\memory.ps1 start-sync ``` `start-sync` encrypts protected local plaintext changes, commits when needed, pulls with rebase, pushes, then decrypts protected entries locally for trusted editing. If setup requires package installation, secrets, key generation, Git config, or user-profile writes, ask for authorization before changing the environment. Repository `AGENTS.md` instructions may restate or refine this rule; follow them for that repository. ## Natural Startup Command When the user asks `iniciar segundo cérebro`, `inicie o segundo cérebro`, `start second brain`, or an equivalent direct startup request: 1. Resolve the active brain root using the core rule above. 2. Determine whether the repository is a template or daily-use from Git remotes and local instructions. 3. In daily-use repositories, run: ```powershell \tools\memory.ps1 start-sync ``` 4. Then run: ```powershell \tools\memory.ps1 github-readiness \tools\memory.ps1 doctor ``` 5. In template repositories, do not run operational `start-sync`; run `github-readiness` and `doctor` only. 6. Summarize blockers and next authorized actions. Ask before installing packages, generating or storing keys, changing Git config, writing user-profile files, or saving secrets. ## MCP Surface Available MCP tools may vary by installed version. Common tools include: - `memory_stats`, `memory_config`, `memory_list`, `memory_recent` - `memory_search`, `memory_semantic_search`, `memory_hybrid_search`, `memory_read` - `memory_add`, `memory_update`, `memory_capture_session` - `memory_tags`, `memory_move`, `memory_delete`, `memory_link` - `memory_reindex`, `memory_embed` - `memory_doctor`, `memory_review`, `memory_synthesize`, `memory_task_brief` - `memory_sync_check`, `memory_encrypt`, `memory_decrypt`, `memory_encrypt_protected` - `memory_bootstrap`, `memory_start_sync`, `memory_device_key_status`, `memory_github_readiness`, when exposed by the server Encrypted bodies are redacted by default. Request decrypted content only when necessary for the user request and appropriate for the storage/security context. If MCP returns transport errors, fall back to CLI/direct reads. A previously loaded MCP host can remain stale until Codex is restarted even when the standalone server is fixed. ## MCP Registration And Validation The MCP server is normally registered as `second-brain` and launched with: ```powershell python \tools\second_brain_mcp.py ``` To validate whether Codex has it registered, run: ```powershell codex mcp list ``` If no server is configured, register it: ```powershell codex mcp add second-brain -- python "\tools\second_brain_mcp.py" ``` Codex may need to be restarted before a newly registered MCP server appears in the native tool list. If the current session reports `unknown MCP server 'second-brain'`, validate the standalone server or CLI, then tell the user to restart Codex before marking native MCP exposure complete. ## CLI Pattern Use the repository's script through the resolved root. On non-Windows systems, use `pwsh` when invoking the PowerShell script. ```powershell \tools\memory.ps1 help \tools\memory.ps1 sync-check \tools\memory.ps1 doctor \tools\memory.ps1 review \tools\memory.ps1 search "" \tools\memory.ps1 index-search "" \tools\memory.ps1 hybrid-search "" \tools\memory.ps1 semantic-search "" \tools\memory.ps1 read \tools\memory.ps1 list \tools\memory.ps1 recent \tools\memory.ps1 tags \tools\memory.ps1 add -Type note -Title "" -Tags tag1,tag2 -Content "<summary>" <brain-root>\tools\memory.ps1 capture-session -Title "<title>" -Content "<summary>" -Completed "<item>" -NextSteps "<item>" <brain-root>\tools\memory.ps1 update <id-or-prefix> -Content "<summary>" <brain-root>\tools\memory.ps1 move <id-or-prefix> -Type decision <brain-root>\tools\memory.ps1 task-brief -Title "<title>" -Content "<summary>" -Owner codex -ExpectedValidation "<command>" <brain-root>\tools\memory.ps1 synthesize "<filter>" -Mode project-state <brain-root>\tools\memory.ps1 reindex <brain-root>\tools\memory.ps1 embed ``` Mutating CLI/MCP operations auto-rebuild `.index/memory.db`. Embeddings are explicit; run `embed` only when semantic retrieval should be refreshed and the privacy policy allows it. ## Retrieval Workflow 1. Search before relying on memory for decisions, preferences, project state, personal context, or research context. 2. Start with 1-3 targeted queries using concrete nouns, project names, acronyms, dates, and likely tags. 3. Use `index-search` for FTS-ranked search over the SQLite index. 4. Use `hybrid-search` when wording may differ from note text. 5. Use `semantic-search` when embeddings exist and the query is conceptual. 6. Read the strongest matching entries with `read` or `memory_read`. 7. Treat entries as evidence, not automatic truth. Prefer high-confidence, recent, source-aware notes. 8. Cite note ids or titles when useful for auditability. ## Writing Workflow ### Autonomous Memory Writes Codex may write to the resolved second-brain without asking when the content is durable, useful beyond the current conversation, and non-secret. Treat this as bounded autonomy: write useful memory proactively, but ask before storing secrets, sensitive personal information, large imported content, external embeddings over private or sensitive notes, or direct edits to `people/` and `projects/` entries unless the user clearly requested them. Write durable memory for: - decisions and rationale - stable preferences - project conventions, architecture, and current state - session summaries and handoffs - reusable references or research findings - explicit next steps that should survive the conversation - task briefs, owner/status, expected validation, and handoffs Use `type`: `note`, `decision`, `project`, `person`, `reference`, `summary`, `task`, or `inbox`. Use `confidence`: `low`, `medium`, or `high`. Use `kind`: `fact`, `observation`, `preference`, `decision`, `hypothesis`, `inference`, or `summary`. Use `status`: `active`, `superseded`, or `archived`. Use `sensitivity`: `public`, `private`, or `sensitive`. Use `capture-session` or `memory_capture_session` at the end of substantive work. Include completed work, decisions, validation, next steps, and open questions. Do not store secrets, credentials, private tokens, or sensitive raw material unless the user explicitly asks and the repository's storage policy supports it. ## Privacy And Encryption Markdown files are the source of truth. SQLite indexes and embeddings are derived artifacts. In daily-use repositories, protected entries must be encrypted before GitHub sync. Protected content includes entries with `sensitivity: sensitive` and directories configured as protected by `config.json`, commonly `people/` and `projects/`. Template repositories keep encryption artifacts but do not require encryption during normal template work. ```powershell <brain-root>\tools\memory.ps1 sync-check <brain-root>\tools\memory.ps1 encrypt <id-or-prefix> <brain-root>\tools\memory.ps1 decrypt <id-or-prefix> <brain-root>\tools\memory.ps1 decrypt-in-place <id-or-prefix> <brain-root>\tools\memory.ps1 encrypt-protected <brain-root>\tools\memory.ps1 decrypt-protected ``` Keep encryption keys outside Git and outside Markdown notes. The default key name is `SECOND_BRAIN_ENCRYPTION_KEY`; repository tooling may also support an OS secret store. Ask before installing packages such as `cryptography`, generating keys, writing secrets, or changing user-level config. External embeddings may send note content to a provider. By default, OpenAI embeddings skip `sensitivity: sensitive` and inactive entries. Use include flags only when the user explicitly wants that content sent externally. ## Governance Use `doctor`/`memory_doctor` to audit frontmatter, duplicate ids, similar titles, broken links, stale index or embeddings, sensitivity policy drift, `.trash`, and redundant summaries. Use `review`/`memory_review` for triage queues: inbox, open questions, active projects, low-confidence notes, older active notes, and suggested maintenance. Use `synthesize`/`memory_synthesize` for reviewable drafts such as project state, decision changelogs, summary consolidation, and archive/superseded suggestions. These commands do not rewrite notes automatically. Use `task-brief`/`memory_task_brief` for delegation memory with owner/status, expected validation, handoffs, and links to decisions/results. ## Bootstrap And Organization Expected directories include `inbox`, `notes`, `projects`, `decisions`, `people`, `references`, `summaries`, `tasks`, `schemas`, `tools`, `.index`, and `.trash`. On MCP `initialize`, daily-use repositories may run bootstrap checks and record/update `references/daily-use-bootstrap-status.md`. Template repositories expose and store the bootstrap flow without treating daily setup as required. Use `install-git-hooks` for repository hooks and `install-agents` to install or refresh a managed global `AGENTS.md` block from `codex/AGENTS.global.md`. Ask before writing user-profile paths when approval is required. ## Index And Embeddings Run `reindex` after manual Markdown edits or bulk changes. Local embeddings use deterministic `local/hash-v1` vectors for offline semantic search. Configuration lives in `config.json`. For higher-quality embeddings, use `-Provider openai` only when `OPENAI_API_KEY` is configured and the selected notes are appropriate for external processing. If no OpenAI model is provided, the tooling resolves the default model from config.