second-brain

Files (5)

• README.md
• SKILL.md
• taxonomy.md · assets/
• _contract.md · references/providers/
• vikunja.md · references/providers/

SKILL.md (first lines)

# Second Brain

Personal knowledge base for work, projects and life. Ingests sources, compiles linked
wiki pages, syncs tasks from the task manager, and answers questions from compiled
knowledge. See `README.md` for setup and the recommended cron jobs.

- **Location:** env `SECOND_BRAIN_PATH` (required)
- **Out of scope:** quiz/education content, secrets (tokens, passwords, keys).

Before any file operation, verify `SECOND_BRAIN_PATH` is set and points to an existing
directory. If it is unset or missing, do not guess or create a vault: ask the user to
configure the path in interactive mode; in cron mode, report the blocker and stop.

## Operating Modes

| Mode | How detected | Rules |
|---|---|---|
| **Interactive** | User is chatting | May ask questions, confirm scope, discuss takeaways |
| **Cron** | Prompt starts with `[CRON:<job>]` | **Never ask questions or wait.** Do the safe part, log it, reply briefly. Anything needing approval goes to `inbox.md` under `## Needs approval` |

## Always Orient First (once per run)

1. Read `SCHEMA.md` (rules, thresholds) and `taxonomy.md` (valid domains).
2. Read `index.md` and the last ~30 lines of `log.md`.
3. Only then act. In a composite cron run (daily), orient once, not per step.

## Architecture

```
$SECOND_BRAIN_PATH/
├── identity.md      who the user is, goals, communication style
├── projects.md      live project state + synced tasks (managed blocks)
├── router.md        lookup table: where everything lives
├── inbox.md         scratchpad; `## Needs approval` section for cron leftovers
├── SCHEMA.md        rules, thresholds, conventions
├── taxonomy.md      the ONLY list of valid domains (and tag vocabulary)
├── index.md         page catalog, grouped by domain
├── log.md           append-only action log
├── weekly/          YYYY-Www.md (ISO week, e.g. 2026-W42)
├── templates/       entity, concept, comparison, query, weekly
├── raw/             immutable sources: articles/ papers/ transcripts/ assets/
├── entities/  concepts/  comparisons/  queries/
```

Skill bundle: `SKILL.md`, `README.md`, `references/providers/*.md` (task manager
adapters), `assets/taxonomy.md` (starter taxonomy to copy into the vault).

## Domains (unified `domain` field)

One field replaces the old `sub_domain` + `org`.

- Value is an id from `taxonomy.md`: a top level (`homelab`, `ai`, `personal`, `work`)
  or one nested level (`work/company-a`, `work/company-b`). Max 2 levels.
- Exactly one primary `domain` per page. Extra context goes in `tags`.
- Prefix match works for queries and indexes: `work` includes all `work/*`.
- **Adding a domain = adding one row to `taxonomy.md`.** Never edit this skill for that.
- **Never invent a domain silently.** Unknown value needed: interactive → propose the new
  row and ask; cron → use the closest parent, add a line to `## Needs approval`.
- Never rename an id. Mark the old row `status: deprecated` with `replaced_by`, then
  migrate pages.
- Legacy `sub_domain`/`org` frontmatter: auto-migrate during lint
  (`sub_domain: work` + `org: company-a` → `domain: work/company-a`).

## Unified Conventions

**Frontmatter (all wiki pages):**
```yaml
---
title: Human readable title
type: entity | concept | comparison | query | weekly
domain: work/company-a            # id from taxonomy.md
tags: [from taxonomy.md vocabulary]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [raw/articles/slug.md]
status: draft | stable | stale
---
```

**Raw files:** `source_url`, `ingested`, `sha256`, `title`. Body is never edited.

**Naming:** lowercase kebab-case ASCII filenames. Content in the source's or user's
language; wikilinks and tags in English.

**Dates:** ISO `YYYY-MM-DD`; weeks via `date +%G-W%V`; timezone from env `TZ`.

**Links:** at least 2 `[[wikilinks]]` per page; no orphans.

**Log line:** `## [YYYY-MM-DD HH:MM] <op> | <title>` + bullets of files touched.
Ops: `ingest`, `tasks`, `weekly`, `inbox`, `query`, `lint`.

**Safety:**
- Never write tokens or credentials to any file or log. Use `[REDACTED]`.
- No pages for passing mentions; thresholds in `SCHEMA.md` (default: central to the
  source, or 2+ mentions).
- Interactive: confirm before touching 10+ pages. Cron: cap at 10 pages per run, defer
  the rest to `## Needs approval`.

## Task Manager (provider-agnostic)

The skill never hardcodes a task manager. It talks to a **provider** through a fixed
contract.

- Active provider: env `TASK_PROVIDER` (default `vikunja`).
- Contract: `references/providers/_contract.md` (operations and normalized fields).
- Adapter: `references/providers/<TASK_PROVIDER>.md` (endpoints, auth, quirks).
- In this skill, use only normalized fields: `id, project_id, project_name, title,
  due, priority, status, url`.
- Task refs in notes: `[<provider>:<id>]`, e.g. `[vikunja:345]`.
- Managed blocks in `projects.md` are provider-neutral:
  ```
  <!-- tasks:start provider=vikunja project=12 domain=work/company-a -->
  - [ ] Task title ([vikunja:345], due 2026-10-20, p3)
  <!-- tasks:end provider=vikunja project=12 -->
  ```
- **Switching provider:** set `TASK_PROVIDER`, add the adapter file, run sync once. Old
  provider blocks are kept and marked `(legacy provider, not synced)`; new blocks are
  created. Nothing is deleted.

From Fritnes/hermes-skills, MIT.

More from Fritnes/hermes-skills