2ndbrain 2026.1.30 → 2026.1.31

package/skills/knowledge/SKILL.md

@@ -0,0 +1,165 @@
+# Skill: knowledge
+
+## Description
+
+Manage a personal knowledge graph with nodes and edges. Nodes represent concepts, people, places, ideas, or anything worth tracking. Edges represent named, directed relationships between nodes (e.g., "works at", "related to", "depends on"). Use this skill to build, query, and traverse the user's personal knowledge graph.
+
+## When to Activate
+
+Activate this skill when any of the following conditions are met:
+
+- The user's message begins with `/knowledge`
+- The user mentions entities and wants them tracked (e.g., "remember that Alice works at Acme Corp", "Bob is my dentist")
+- The user asks about relationships between things (e.g., "how is X related to Y", "what do I know about X", "who works at Y")
+- The user wants to create, update, or explore connections between concepts
+- The user asks to list or browse known entities
+
+## Available Tools
+
+- `mcp__pg__query` -- Execute SQL queries against the PostgreSQL database.
+
+No other tools are permitted for this skill.
+
+## Database Tables
+
+### `knowledge_nodes`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `name` | TEXT NOT NULL | Name of the entity (person, concept, place, etc.) |
+| `note` | TEXT | Optional descriptive note about the entity |
+
+### `knowledge_edges`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `source_id` | INTEGER NOT NULL | FK to `knowledge_nodes.id` (the "from" node) |
+| `target_id` | INTEGER NOT NULL | FK to `knowledge_nodes.id` (the "to" node) |
+| `name` | TEXT NOT NULL | Relationship label (e.g., "works at", "is friend of") |
+
+There is a unique constraint on `(source_id, target_id, name)` to prevent duplicate edges.
+
+### `embeddings` (for post-create embedding queue only)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `entity_type` | TEXT NOT NULL | Type of entity (use `'node'` for knowledge nodes) |
+| `entity_id` | INTEGER NOT NULL | The `id` of the knowledge node |
+
+## Operations
+
+### Create a Node
+
+When the user mentions a new concept, person, place, or idea to track.
+
+```sql
+INSERT INTO knowledge_nodes (name, note)
+VALUES ('Alice', 'Friend from university, works in data science')
+RETURNING id, name;
+```
+
+Before creating a node, check if one with the same name already exists to avoid duplicates:
+
+```sql
+SELECT id, name, note FROM knowledge_nodes WHERE name ILIKE 'Alice';
+```
+
+If a match exists, ask the user whether to update the existing node or create a new one.
+
+### Create an Edge
+
+When the user describes a relationship between two entities.
+
+```sql
+INSERT INTO knowledge_edges (source_id, target_id, name)
+VALUES (1, 2, 'works at')
+ON CONFLICT (source_id, target_id, name) DO NOTHING;
+```
+
+Both the source and target nodes must exist before creating an edge. If either does not exist, create the missing node(s) first (with user confirmation if the intent is ambiguous).
+
+### Query a Node by Name
+
+When the user asks "what do I know about X" or mentions an entity by name.
+
+```sql
+SELECT id, name, note, created_at
+FROM knowledge_nodes
+WHERE name ILIKE '%' || 'search term' || '%';
+```
+
+### Traverse Edges from a Node
+
+When the user asks about relationships or connections (e.g., "how is X connected", "what is related to X").
+
+Outgoing relationships (what does X relate to):
+
+```sql
+SELECT kn.name AS target, ke.name AS relationship
+FROM knowledge_edges ke
+JOIN knowledge_nodes kn ON kn.id = ke.target_id
+WHERE ke.source_id = <node_id>;
+```
+
+Incoming relationships (what relates to X):
+
+```sql
+SELECT kn.name AS source, ke.name AS relationship
+FROM knowledge_edges ke
+JOIN knowledge_nodes kn ON kn.id = ke.source_id
+WHERE ke.target_id = <node_id>;
+```
+
+For a complete picture, run both queries and present all connections.
+
+### Full-Text Search
+
+Search across both the `name` and `note` fields of knowledge nodes.
+
+```sql
+SELECT id, name, note, created_at
+FROM knowledge_nodes
+WHERE name ILIKE '%' || 'search term' || '%'
+   OR note ILIKE '%' || 'search term' || '%'
+ORDER BY updated_at DESC
+LIMIT 10;
+```
+
+### Update a Node
+
+When the user wants to add or change information about an existing entity.
+
+```sql
+UPDATE knowledge_nodes
+SET note = 'Updated information here',
+    updated_at = NOW()
+WHERE id = <node_id>;
+```
+
+### Post-Create: Queue for Embedding
+
+After successfully creating a knowledge node, attempt to queue it for embedding generation.
+
+```sql
+INSERT INTO embeddings (entity_type, entity_id)
+VALUES ('node', <new_node_id>)
+ON CONFLICT DO NOTHING;
+```
+
+**Important:** The `embeddings` table only exists when the embeddings engine is enabled. If this query fails because the table does not exist, silently ignore the error and proceed normally. The knowledge node is already saved -- embedding is optional. Do not report the embedding queue failure to the user.
+
+## Restrictions and Notes
+
+- Always use `mcp__pg__query` for database operations. Do not use any other tool.
+- Edges are directed: "Alice works at Acme" means Alice is the source and Acme is the target. Choose direction to reflect the natural reading of the relationship.
+- Before creating nodes, always check for existing nodes with similar names to prevent duplicates.
+- When presenting graph data to the user, format it clearly -- list relationships in a readable way rather than dumping raw SQL results.
+- If the user describes multiple entities and relationships in one message, process them all (create nodes first, then edges).
+- Never delete nodes or edges unless the user explicitly requests it. Deleting a node cascades to all its edges.
+- When searching, if no exact match is found, try broader partial matches and present the closest results.

package/skills/project-manage/SKILL.md

@@ -0,0 +1,216 @@
+# Skill: project-manage
+
+## Description
+
+Manage projects, specifications, and issues. Use this skill to create projects, add tasks and issues, write specifications, track progress, mark items complete, and get project status summaries. Supports hierarchical sub-tasks and nested specifications.
+
+## When to Activate
+
+Activate this skill when any of the following conditions are met:
+
+- The user's message begins with `/project`
+- The user mentions tasks, projects, or work items (e.g., "I need to do X", "add a task for Y", "create a project for Z")
+- The user asks about project status (e.g., "what's the status of project Z", "what tasks are open", "what's left to do")
+- The user wants to track issues, bugs, or blockers
+- The user wants to document a specification, requirement, or architecture decision
+- The user marks something as done or complete
+
+## Available Tools
+
+- `mcp__pg__query` -- Execute SQL queries against the PostgreSQL database.
+
+No other tools are permitted for this skill.
+
+## Database Tables
+
+### `projects`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `name` | TEXT NOT NULL | Name of the project |
+
+### `issues`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `project_id` | INTEGER | FK to `projects.id` (nullable -- issues can exist without a project) |
+| `parent_id` | INTEGER | FK to `issues.id` (nullable -- for sub-task hierarchy) |
+| `note` | TEXT NOT NULL | Description of the issue or task |
+| `completed` | BOOLEAN NOT NULL DEFAULT FALSE | Whether the issue is resolved |
+
+### `specifications`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `project_id` | INTEGER NOT NULL | FK to `projects.id` |
+| `parent_id` | INTEGER | FK to `specifications.id` (nullable -- for nested specs) |
+| `note` | TEXT NOT NULL | Specification content |
+
+## Operations
+
+### Create a Project
+
+When the user wants to start tracking a new project.
+
+```sql
+INSERT INTO projects (name)
+VALUES ('My New Project')
+RETURNING id, name, created_at;
+```
+
+Before creating, check if a project with the same name already exists:
+
+```sql
+SELECT id, name FROM projects WHERE name ILIKE 'My New Project';
+```
+
+### Create an Issue or Task
+
+When the user wants to add a task, bug, blocker, or to-do item.
+
+```sql
+INSERT INTO issues (project_id, note)
+VALUES (<project_id>, 'Description of the task')
+RETURNING id, note, created_at;
+```
+
+If the user does not specify a project, either ask which project it belongs to, or create the issue without a project (`project_id = NULL`).
+
+### Create a Sub-Task
+
+Issues support hierarchical nesting via `parent_id`. When the user wants to break a task into smaller pieces.
+
+```sql
+INSERT INTO issues (project_id, parent_id, note)
+VALUES (<project_id>, <parent_issue_id>, 'Sub-task description')
+RETURNING id, note, created_at;
+```
+
+### Create a Specification
+
+When the user wants to document a requirement, architecture decision, or design note for a project.
+
+```sql
+INSERT INTO specifications (project_id, note)
+VALUES (<project_id>, 'Specification content here')
+RETURNING id, note, created_at;
+```
+
+Specifications also support nesting via `parent_id` for hierarchical documentation:
+
+```sql
+INSERT INTO specifications (project_id, parent_id, note)
+VALUES (<project_id>, <parent_spec_id>, 'Child specification detail')
+RETURNING id, note, created_at;
+```
+
+### Mark an Issue as Complete
+
+When the user says something is done, finished, or complete.
+
+```sql
+UPDATE issues
+SET completed = TRUE, updated_at = NOW()
+WHERE id = <issue_id>;
+```
+
+To reopen an issue:
+
+```sql
+UPDATE issues
+SET completed = FALSE, updated_at = NOW()
+WHERE id = <issue_id>;
+```
+
+### Project Status Summary
+
+When the user asks for an overview of a project or all projects. Show counts of open and closed issues.
+
+For a single project:
+
+```sql
+SELECT
+  p.name AS project,
+  COUNT(i.id) FILTER (WHERE NOT i.completed) AS open_issues,
+  COUNT(i.id) FILTER (WHERE i.completed) AS closed_issues,
+  COUNT(i.id) AS total_issues
+FROM projects p
+LEFT JOIN issues i ON i.project_id = p.id
+WHERE p.id = <project_id>
+GROUP BY p.id, p.name;
+```
+
+For all projects:
+
+```sql
+SELECT
+  p.name AS project,
+  COUNT(i.id) FILTER (WHERE NOT i.completed) AS open_issues,
+  COUNT(i.id) FILTER (WHERE i.completed) AS closed_issues,
+  COUNT(i.id) AS total_issues
+FROM projects p
+LEFT JOIN issues i ON i.project_id = p.id
+GROUP BY p.id, p.name
+ORDER BY p.name;
+```
+
+### List Open Issues for a Project
+
+```sql
+SELECT id, note, created_at, parent_id
+FROM issues
+WHERE project_id = <project_id>
+  AND completed = FALSE
+ORDER BY created_at ASC;
+```
+
+### View Sub-Task Hierarchy
+
+To display an issue with its sub-tasks:
+
+```sql
+SELECT id, note, completed, parent_id, created_at
+FROM issues
+WHERE parent_id = <parent_issue_id>
+ORDER BY created_at ASC;
+```
+
+### List Specifications for a Project
+
+```sql
+SELECT id, note, parent_id, created_at
+FROM specifications
+WHERE project_id = <project_id>
+ORDER BY created_at ASC;
+```
+
+### Search Across Issues
+
+```sql
+SELECT i.id, i.note, i.completed, p.name AS project
+FROM issues i
+LEFT JOIN projects p ON p.id = i.project_id
+WHERE i.note ILIKE '%' || 'search term' || '%'
+ORDER BY i.created_at DESC
+LIMIT 10;
+```
+
+## Restrictions and Notes
+
+- Always use `mcp__pg__query` for database operations. Do not use any other tool.
+- When the user mentions a project by name, look it up first. If multiple projects match, list them and ask the user to clarify.
+- When marking items complete, confirm which specific issue is being completed. If the user says "mark it done" ambiguously, ask which task they mean.
+- Present project status in a clear, concise format. Use counts and lists, not raw SQL output.
+- Issues can exist without a project (`project_id = NULL`). These are standalone tasks.
+- When showing sub-tasks, indicate the hierarchy clearly (e.g., indent or label parent/child relationships).
+- Never delete projects, issues, or specifications unless the user explicitly asks for deletion.
+- When a project has many issues, summarize by status (open vs. closed) rather than listing every single one, unless the user asks for a full list.

package/skills/recall/SKILL.md

@@ -0,0 +1,182 @@
+# Skill: recall
+
+## Description
+
+Search across all personal data using natural language. This skill provides unified search over journal entries, knowledge graph nodes, project issues, specifications, and conversation history. It uses semantic vector search when embeddings are available, and falls back to text-based search otherwise.
+
+## When to Activate
+
+Activate this skill automatically when the user expresses search or recall intent. Common triggers include:
+
+- "Find..." or "Search for..."
+- "Remember when..." or "What was that thing about..."
+- "What did I say about..."
+- "Do I have anything on..."
+- "Look up..." or "Can you find..."
+- Any question that requires searching across the user's stored data
+
+This skill does not require a slash command prefix. It activates whenever the user appears to be searching their personal data.
+
+## Available Tools
+
+- `mcp__pg__query` -- Execute SQL queries against the PostgreSQL database.
+- `embed_query` -- Convert a text string into a vector embedding for semantic search. Accepts `{ text: "search query" }` and returns `{ vector: [...], dimensions: N }`.
+
+## Database Tables
+
+### `embedding_config` (read-only, check availability)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | INTEGER | Always 1 (single-row table) |
+| `provider` | TEXT | Embedding provider name |
+| `model` | TEXT | Embedding model name |
+| `dimensions` | INTEGER | Vector dimensions |
+
+### `embeddings` (for semantic search)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `entity_type` | TEXT | Type: `'journal'`, `'node'`, `'issue'`, `'message'`, etc. |
+| `entity_id` | INTEGER | ID in the source entity table |
+| `vector` | VECTOR | Embedding vector |
+
+### Entity Tables (joined for full content)
+
+- `journal` -- `id`, `note`, `created_at`
+- `knowledge_nodes` -- `id`, `name`, `note`, `created_at`
+- `issues` -- `id`, `note`, `completed`, `project_id`, `created_at`
+- `specifications` -- `id`, `note`, `project_id`, `created_at`
+- `conversation_messages` -- `id`, `content`, `role`, `created_at`
+
+## Operations
+
+### Step 1: Check Semantic Search Availability
+
+Before attempting semantic search, check whether the embeddings engine is configured.
+
+```sql
+SELECT dimensions FROM embedding_config WHERE id = 1;
+```
+
+- If this query **succeeds and returns a row**, semantic search is available. Proceed to Step 2a.
+- If this query **fails** (table does not exist) or **returns no rows**, semantic search is unavailable. Skip to Step 2b (text fallback).
+
+### Step 2a: Semantic Search (preferred)
+
+When semantic search is available, use the `embed_query` tool to vectorize the user's search query, then find the nearest matches.
+
+1. Call `embed_query` with the user's search text:
+
+```
+embed_query({ text: "the user's search query" })
+```
+
+This returns `{ vector: [0.123, ...], dimensions: 1536 }`.
+
+2. If `embed_query` succeeds, search for nearest neighbors using cosine distance:
+
+```sql
+SELECT entity_type, entity_id,
+       1 - (vector <=> '<vector_string>'::vector) AS similarity
+FROM embeddings
+WHERE vector IS NOT NULL
+ORDER BY vector <=> '<vector_string>'::vector
+LIMIT 10;
+```
+
+Replace `<vector_string>` with the vector array returned by `embed_query`, formatted as a string (e.g., `'[0.123, 0.456, ...]'`).
+
+3. Join the results back to their source tables to retrieve the full content. Use the `entity_type` to determine which table to join:
+
+For journal entries (`entity_type = 'journal'`):
+```sql
+SELECT j.id, j.note, j.created_at
+FROM journal j WHERE j.id = <entity_id>;
+```
+
+For knowledge nodes (`entity_type = 'node'`):
+```sql
+SELECT kn.id, kn.name, kn.note, kn.created_at
+FROM knowledge_nodes kn WHERE kn.id = <entity_id>;
+```
+
+For issues (`entity_type = 'issue'`):
+```sql
+SELECT i.id, i.note, i.completed, p.name AS project_name, i.created_at
+FROM issues i
+LEFT JOIN projects p ON p.id = i.project_id
+WHERE i.id = <entity_id>;
+```
+
+For specifications (`entity_type = 'spec'`):
+```sql
+SELECT s.id, s.note, p.name AS project_name, s.created_at
+FROM specifications s
+LEFT JOIN projects p ON p.id = s.project_id
+WHERE s.id = <entity_id>;
+```
+
+4. If `embed_query` fails (returns an error), fall through to Step 2b.
+
+### Step 2b: Text Fallback Search
+
+When semantic search is unavailable or `embed_query` fails, search across all entity tables using case-insensitive text matching.
+
+**Important:** When using this fallback, inform the user: "Using text search (semantic search is not available)."
+
+Search each table independently and combine results:
+
+```sql
+-- Journal entries
+SELECT 'journal' AS source, id, note AS content, created_at
+FROM journal
+WHERE note ILIKE '%' || 'search term' || '%'
+ORDER BY created_at DESC
+LIMIT 5;
+
+-- Knowledge nodes
+SELECT 'knowledge' AS source, id, name || ': ' || COALESCE(note, '') AS content, created_at
+FROM knowledge_nodes
+WHERE name ILIKE '%' || 'search term' || '%'
+   OR note ILIKE '%' || 'search term' || '%'
+ORDER BY created_at DESC
+LIMIT 5;
+
+-- Issues
+SELECT 'issue' AS source, id, note AS content, created_at
+FROM issues
+WHERE note ILIKE '%' || 'search term' || '%'
+ORDER BY created_at DESC
+LIMIT 5;
+
+-- Specifications
+SELECT 'spec' AS source, id, note AS content, created_at
+FROM specifications
+WHERE note ILIKE '%' || 'search term' || '%'
+ORDER BY created_at DESC
+LIMIT 5;
+```
+
+### Step 3: Source Attribution
+
+Always present results with clear attribution to their source. The user should know where each result came from.
+
+Format examples:
+- "From your journal on Jan 15: ..."
+- "From your knowledge graph -- Alice: works at Acme Corp"
+- "From project X, issue #3: ..."
+- "From a specification in project Y: ..."
+
+Include dates and context to help the user identify the result they are looking for.
+
+## Restrictions and Notes
+
+- Always try semantic search first when available. It produces better results for natural language queries.
+- If semantic search is unavailable, always use the text fallback. Never tell the user that search is impossible.
+- Always attribute results to their source table and include timestamps.
+- If no results are found across any table, say so clearly and suggest alternative search terms or phrasing.
+- Do not modify any data during recall operations. This skill is read-only -- it only searches.
+- When presenting multiple results, rank them by relevance (similarity score for semantic, or recency for text fallback).
+- If the user's query seems to target a specific data type (e.g., "my journal entries about X"), you may search only the relevant table rather than all tables.
+- Keep the result presentation concise. Summarize long entries rather than dumping full content, unless the user asks for detail.