Cortex

Capture conversation summaries and web content to daily notes synced to GitHub.

Conversation Summary Mode

When the user wants to save or summarize the current conversation:

Step 1: Ask for Instructions

Ask: "Any specific focus or instructions for the summary?"

Step 2: Ask About Topics

Ask: "Any topics to link this to? (e.g., [[AI Coding]], [[Architecture]])"

Before suggesting new topics, search for existing notes that match. If found:

• Single match: "Should I add this to [[AI Coding]]?"
• Multiple matches: "Found related notes: [[AI Coding]], [[AI Tools]]. Which one?"

Step 3: Extract Key Ideas

Review the conversation and extract:

• Main concepts and decisions discussed
• Action items or conclusions
• Any URLs or resources mentioned

Step 4: Create/Update Topic Docs (if specified)

If user wants to link to a topic:

• Fetch existing topic file (or create new)
• Add a reference to today's daily note with 1-sentence summary
• Push updated topic file

Step 5: Format as Daily Note Entry

Create an entry with timestamp, key ideas, related notes, and links.

Timestamp: Read timezone from scripts/config.json and calculate the current local time. Use format HH:MM (24-hour).

Step 6: Save to GitHub

Fetch existing daily note, append new entry, push back.

Example Conversation

User: Save this conversation
Claude: Any specific focus or instructions for the summary?
User: Focus on the architecture decisions we made
Claude: Any topics to link this to? I found [[Event-Driven Architecture]] in your notes.
User: Yes, add it there. Also create a new note for System Design.
Claude: Got it. I'll update [[Event-Driven Architecture]] and create [[System Design]].

Saved to 2026-01-03.md:
## 14:30 - Architecture Discussion

### Key Ideas
- Decided to use event-driven architecture for the notification system
- Will implement retry logic with exponential backoff
- See [[Event-Driven Architecture]] for more details

### Related Notes
- [[Event-Driven Architecture]]
- [[System Design]]

### Links
- [EDA Article](https://example.com/eda) - reference article discussed

Updated [[Event-Driven Architecture]] with link to today's discussion.
Created [[System Design]] with initial notes.

Link Summary Mode

When the user pastes a URL without context:

Step 1: Offer to Summarize

Ask: "Would you like me to summarize this link?"

Step 2: Get Focus Instructions

If yes, ask: "Any specific focus or instructions for the summary?"

Step 3: Fetch and Summarize

Retrieve the page content and create a summary based on instructions.

Step 4: Save to Daily Notes

Add the link with its summary to the daily notes.

Example Conversation

User: https://example.com/article-about-microservices
Claude: Would you like me to summarize this link?
User: Yes, focus on the deployment strategies
Claude: Any topics to link this to? I found [[Microservices]] in your notes.
User: Yes, and also [[Deployment Strategies]]
Claude: Got it. Keep it brief?
User: Yes

[Fetches and summarizes the article]

Saved to 2026-01-03.md:
## 15:00 - Link Summary

### Key Ideas
- Article recommends blue-green deployments for microservices
- Canary releases reduce risk for critical services
- Feature flags enable gradual rollouts

### Related Notes
- [[Microservices]]
- [[Deployment Strategies]]

### Links
- [Microservices Deployment Strategies](https://example.com/article-about-microservices) - deployment patterns

Updated [[Microservices]] with link to this article.

Daily Notes Format

Files are named YYYY-MM-DD.md (one file per day). Multiple sessions throughout the day all append to the same file.

Ordering Multiple Entries

When appending a new entry:

1. Fetch existing daily note
2. Find the # Cortex section (or create it at the bottom if missing)
3. Parse existing entries by their ## HH:MM timestamps
4. Insert new entry in chronological order (don't intermix - each summary stays as a complete block)
5. Push updated file

The exact timestamp isn't critical - entries just need to be roughly in order of when they happened.

Example: 2026-01-03.md

# Cortex

## 14:30 - Architecture Discussion

### Key Ideas
- Decided to use event-driven architecture
- Will implement retry logic with exponential backoff
- See [[Event-Driven Architecture]] for more details

### Related Notes
- [[Event-Driven Architecture]]
- [[System Design]]

### Links
- [EDA Article](https://example.com/eda) - reference article

---

## 15:00 - Link Summary

### Key Ideas
- Blue-green deployments recommended for microservices

### Related Notes
- [[Microservices]]
- [[Deployment Strategies]]

### Links
- [Microservices Guide](https://example.com/guide) - deployment patterns

---

The # Cortex header marks the section for cortex entries. When appending, add entries after this header.

Format Rules

• Filename: YYYY-MM-DD.md
• Section header: # Cortex at the bottom of the file
• Entry header: ## HH:MM - Title
• Key Ideas section: ### Key Ideas with bullet points
• Related Notes section (optional): ### Related Notes with [[Topic Name]] links - only include if there are related notes (e.g., [[Claude Code]], [[Architecture Patterns]])
• Links section: ### Links with [Title](URL) - description
• Entry separator: --- between entries

Internal Links

Use Obsidian-style [[wiki links]] to connect notes.

Inline Links (wiki-style)

Reference topics naturally in sentences:

This discussion covered [[AI Coding]] best practices and [[Architecture Patterns]].

Related Notes Section

List related topics at the end of an entry:

### Related Notes
- [[AI Coding]]
- [[Cloudflare]]
- [[Architecture Patterns]]

Topic Documents

Topic docs are standalone notes for recurring themes, projects, or reference material. They live in the same notes/ folder as daily notes.

Finding Existing Topics

Before creating a new topic, search the existing notes in the repo:

1. Check for notes with matching or similar names to the topic being discussed
2. If found, suggest: "Should I add this to [[AI Coding]]?"
3. If multiple matches: "Found related notes: [[AI Coding]], [[AI Tools]], [[Coding Best Practices]]. Which one?"

To check if a topic exists, try fetching it:

cd /mnt/skills/user/cortex/scripts
uv run github_sync.py --fetch "notes/AI Coding.md"

When to Create Topics

• Not everything needs a topic file - use judgment
• Create topics for recurring themes, projects, or reference material
• Daily notes can reference topics for deeper detail

Topic Document Structure

# AI Coding

## Overview
Brief description of the topic.

## Notes
- [[2026-01-03]] - Discussed using AI for code review
- [[2026-01-04]] - Explored cursor-based editing workflows

## Related Notes
- [[Architecture Patterns]]
- [[Code Review]]

## Links

AI coding tools have evolved rapidly, with IDE integrations like Cursor leading the way in seamless code generation. For terminal-based workflows, Claude Code offers powerful multi-file editing capabilities. Understanding the underlying architectures is essential for building effective tools.

- [Cursor](https://cursor.com) - AI-powered code editor built on VS Code with tab completion, inline editing, and chat-based code generation
- [Claude Code](https://claude.ai/claude-code) - Command-line coding assistant from Anthropic with file editing and multi-file refactoring
- [Building AI Coding Assistants](https://example.com/ai-coding-guide) - Guide on architectures, prompt engineering, and context management

Link format:

• Bullet list with [Title](URL) - description
• Keep descriptions concise (one line)

When multiple links exist, add a brief overview (1-2 sentences) at the top of the Links section that synthesizes the resources. Update the overview when new links are added.

Relationship with Daily Notes

• Daily note: Brief summary of what was discussed
• Topic file: More detailed info, expands on concepts
• Daily note can reference topic: "See [[AI Coding]] for more details"
• Topic links back to daily note with 1-sentence summary

Obsidian Markdown Reference

Cortex uses Obsidian-flavored markdown. Reference: https://help.obsidian.md/obsidian-flavored-markdown

Supported Extensions

Syntax	Description
[[Link]]	Internal links to other notes
![[Link]]	Embed files
![[Link#^id]]	Block references
^id	Defining a block
[^id]	Footnotes
%%Text%%	Comments
~~Text~~	Strikethroughs
==Text==	Highlights
```	Code blocks
- [ ]	Incomplete task
- [x]	Completed task
> [!note]	Callouts
|	Tables

Configuration

Edit scripts/config.json to configure GitHub storage:

{
  "github_repo": "mberg/cortex",
  "github_token": "github_pat_xxxxx",
  "github_branch": "main",
  "github_notes_dir": "notes",
  "timezone": "America/New_York"
}

• github_repo: Your repository in username/repo-name format
• github_token: Personal Access Token with repo scope. Create at: https://github.com/settings/tokens
• github_branch: Target branch (default: main)
• github_notes_dir: Directory in repo for notes (default: notes)
• timezone: User's timezone for timestamps (e.g., America/New_York, Europe/London, Asia/Tokyo)

Using Timezone for Timestamps

When adding notes, read the timezone from config and calculate the local time:

import json
from datetime import datetime
from zoneinfo import ZoneInfo

# Read config
with open("config.json") as f:
    config = json.load(f)

# Get current time in user's timezone
tz = ZoneInfo(config.get("timezone", "UTC"))
local_time = datetime.now(tz)

# Format for note header: "## 14:30 - Title"
timestamp = local_time.strftime("%H:%M")

# Format for daily note filename: "2026-01-03.md"
date_str = local_time.strftime("%Y-%m-%d")

GitHub Workflow

Important: Must cd into the scripts directory so github_sync.py can find config.json.

Step 1: Fetch existing daily note (if any)

cd /mnt/skills/user/cortex/scripts
uv run github_sync.py --fetch notes/2026-01-03.md > /tmp/2026-01-03.md

If the file doesn't exist yet, create it empty.

Step 2: Append new entry

cat >> /tmp/2026-01-03.md << 'EOF'

## 14:30 - Session Summary

### Key Ideas
- Main concept discussed
- Decision made

### Links
- [Resource](https://example.com) - description

---
EOF

Step 3: Push back to GitHub

cd /mnt/skills/user/cortex/scripts
uv run github_sync.py \
  --file /tmp/2026-01-03.md \
  --dest notes/2026-01-03.md \
  -m "Add notes for 2026-01-03"

Key Details

• Working directory matters — Must cd into scripts/ so github_sync.py can find config.json
• Config location — The script looks for config.json in the same directory as the script itself
• Dest path — The --dest is relative to the repo root (e.g., notes/2026-01-03.md)