second-brain

name	second-brain
description	Capture reusable Codex work memory into Notion, including decisions, bugfixes, how-tos, architecture notes, gotchas, setup steps, and session summaries. Use only when the user asks to remember, save, capture, retrieve, or update second-brain knowledge.

Second Brain

Use this skill to save or retrieve high-signal Codex work memory in the user's Notion second-brain databases.

Non-Negotiable Rules

• Preserve user-supplied memory content as provided. Do not redact secrets, credentials, paths, logs, URLs, or exact errors from content the user explicitly asks to save.
• Use best effort to keep high-signal details instead of dropping fields because they look sensitive.
• Do not silently crawl local session artifacts or logs. Save supplied logs only when the user explicitly asks to include them or provides the content directly.
• Raw transcript references are not part of MVP. Do not save transcript_path, session JSONL paths, raw transcript URLs, or other pointers to raw transcript artifacts.
• Automatic Stop hook capture is not part of MVP. Only capture when the user explicitly asks.
• Automatic SessionStart retrieval is not part of this plugin. Do not inject second-brain context unless the user explicitly asks.
• If Notion auth is unavailable, report that the memory was not saved. Do not write a local cache or local outbox fallback.

Required References

Read these references before acting:

1. references/memory-taxonomy.md
2. references/capture-policy.md
3. references/storage-policy.md
4. references/notion-memory-database.md

Read references/retrieval-policy.md only when the user explicitly asks to retrieve, recall, search, or reference second-brain memory.

Capture Workflow

1. Determine the project name when the user provides one:

   • Example: $second-brain second brain 프로젝트에 현재까지의 내용 정리해줘
   • Project name: second brain
   • If the user does not provide a project name, save the memory without a project relation and say that no project was linked.

2. If a project name is present, resolve the Project Index row before preparing the memory:

   • Fetch Codex Project Index to verify the Project Name title property and Memories relation property.
   • Search the Project Index data source for the project name.
   • Reuse an exact title match when one exists.
   • If no exact match exists, prepare a project row:

python3 scripts/project_index.py prepare --project-json <candidate-project-json>

• Create the project row in Codex Project Index with the returned properties.
• Keep the created or reused project page URL; memory relation values use a JSON array of project page URLs.

3. Determine the memory type:

   • session-summary
   • decision
   • bugfix
   • how-to
   • architecture
   • research
   • gotcha
   • setup
   • test-result
   • dependency
   • prompt-pattern

4. Build a candidate JSON record with:

   • title
   • memory_type
   • project_name, when known
   • project_page_url, when a Project Index row was created or reused
   • repo, if known
   • repo_url, if known
   • branch, if known
   • cwd, if known
   • tags
   • related_files
   • related_refs
   • retrieval_hints
   • summary
   • context
   • what_was_learned
   • decisions
   • commands_and_results
   • gotchas
   • followups

5. Keep command output summarized:

   • Good: npm test passed
   • Good: pytest failed in test_auth_refresh due to missing fixture
   • For full logs or bulky data, include them only when the user explicitly asks to preserve that detail.
   • Do not add raw transcript pointers. If useful information came from a transcript, summarize the reusable facts in the normal memory sections.

6. Run the deterministic preparation script from the plugin root:

python3 scripts/capture_memory.py prepare --record-json <candidate-json>

Use stdin with --record-json - when convenient.

7. If the script returns status = blocked, do not write to Notion. Report the schema or Notion-preparation reason and ask for the missing required information if needed.

8. If the script returns status = prepared, use the returned notion.properties and notion.content.

9. Before creating or updating pages through Notion MCP:

   • Fetch the Codex Memory database or data source to verify schema and title property.
   • Verify that Project exists on Codex Memory and Memories exists on Codex Project Index when a project relation is being saved.
   • Search/query for an existing row with the same Duplicate Key.
   • Update exact duplicates; otherwise create a new page.
   • If updating an existing memory and it already has project relations, preserve them and add the resolved project URL if missing.
   • Fetch notion://docs/enhanced-markdown-spec if using rich Notion markdown beyond plain headings/lists.

10. After the memory write, fetch the memory page or project page to verify the relation:

    • Codex Memory.Project should contain the Project Index page URL.
    • Codex Project Index.Memories should contain the memory page URL.

11. If Notion write fails because of auth, permission, schema, or network issues, report the failure. Do not save a local fallback copy.

12. Return a concise result:

    • action: created, updated, failed, or blocked
    • page title
    • memory type
    • project name and project page id or URL when linked
    • tags
    • retrieval hints
    • Notion page id when available

Notion Setup Workflow

Run this when the user asks to set up, initialize, bootstrap, or configure the second-brain Notion workspace, especially with a request like:

• $second-brain setup https://app.notion.com/p/<page-id>
• second brain을 이 Notion page에 세팅해줘: <page-url>

Setup creates Notion databases under the user's chosen private root page and writes user-specific configuration outside the plugin directory.

Example root page URL format:

https://app.notion.com/p/<your-root-page-id>

1. Run the setup doctor from the plugin root:

python3 scripts/setup_notion.py doctor

If doctor reports that Notion MCP is not registered, tell the user to run:

codex mcp add notion --url https://mcp.notion.com/mcp --oauth-resource https://mcp.notion.com
codex mcp login notion

2. Use Notion MCP to verify the live connection:

   • Fetch self or otherwise verify the current Notion workspace identity.
   • Fetch the provided root page URL or page ID to verify the authenticated user can access it.
   • If Notion MCP auth fails, report the failed setup and ask the user to run codex mcp login notion.

3. Prepare the setup plan:

python3 scripts/setup_notion.py prepare --root-page-url <root-page-url>

Use the returned schemas to create these databases under the root page:

• Codex Memory
• Codex Project Index

4. Create the two base databases with Notion MCP create-database:

   • Parent: the provided root page ID
   • Title/schema: Codex Project Index from the setup plan
   • Title/schema: Codex Memory from the setup plan

5. Fetch both created databases or data sources and record:

• database id
• data source URL, like collection://...

6. Add the cross-database relation after both data source IDs are known:

• Codex Project Index.Memories relates to Codex Memory
• Codex Memory.Project is the synced relation back to Codex Project Index

Use Notion MCP update-data-source on the Codex Project Index data source with:

ADD COLUMN "Memories" RELATION('<MEMORY_DATA_SOURCE_ID>', DUAL 'Project')

7. Ask the user for permission before writing config outside the plugin directory. The default config path is:

~/.config/second-brain-notion/config.json

SECOND_BRAIN_CONFIG can override this path.

8. After permission, write config with:

python3 scripts/setup_notion.py write-config \
  --root-page-url <root-page-url> \
  --project-database-id <project-database-id> \
  --project-data-source-url <project-data-source-url> \
  --memory-database-id <memory-database-id> \
  --memory-data-source-url <memory-data-source-url> \
  --yes

Add --force only when intentionally overwriting an existing config file.

9. Verify setup:
   • Fetch Codex Project Index and confirm Memories exists.
   • Fetch Codex Memory and confirm Project exists.
   • Report the config path and both data source URLs.

Do not store credentials in config. Keep workspace-specific page IDs, database IDs, and data source URLs in the external user config, not in public plugin files.

Manual Retrieval Workflow

Run this only when the user explicitly asks to use second-brain context, for example:

• $second-brain retrieve auth middleware
• second brain에서 관련 내용 찾아봐
• 이 작업 전에 예전 memory 참고해줘
• remembered context 불러와줘

Steps:

1. Read references/retrieval-policy.md.
2. Determine the current repo/cwd/branch/files from local context when useful.
3. Use Notion MCP search/query directly.
4. Search Codex Memory for repo, tags, related files, and retrieval hints.
5. Exclude stale and archived by default.
6. Return at most 5 relevant memories, each compressed to 3-4 bullets.
7. If Notion MCP is unavailable, report that retrieval cannot be completed. There is no local cache fallback.