diff --git a/profiles/opencode.nix b/profiles/opencode.nix index 5f4b73e..976ed9b 100644 --- a/profiles/opencode.nix +++ b/profiles/opencode.nix @@ -74,7 +74,7 @@ command = ["bunx" "opensrc-mcp"]; }; overseer = { - enabled = false; + enabled = true; type = "local"; command = ["${pkgs.overseer}/bin/os" "mcp"]; }; diff --git a/profiles/opencode/skill/cog/SKILL.md b/profiles/opencode/skill/cog/SKILL.md deleted file mode 100644 index e875ec1..0000000 --- a/profiles/opencode/skill/cog/SKILL.md +++ /dev/null @@ -1,406 +0,0 @@ ---- -name: cog -description: Persistent knowledge graph memory via Cog MCP. Use when recording insights, querying prior knowledge, or managing memory consolidation. -metadata: - author: trycog - version: "1.0.0" ---- - -# Cog Memory System - -Persistent knowledge graph for teams. Concepts (engrams) linked via relationships (synapses). Spreading activation surfaces connected knowledge. - -## Core Workflow - -``` -1. UNDERSTAND task (read files, parse request) -2. QUERY Cog with specific keywords <- MANDATORY, no exceptions -3. WAIT for results -4. EXPLORE/IMPLEMENT guided by Cog knowledge -5. RECORD insights as short-term memories during work -6. CONSOLIDATE memories after work (reinforce valid, flush invalid) -``` - -**Hierarchy of truth:** Current code > User statements > Cog knowledge - ---- - -## Visual Indicators (MANDATORY) - -Print before EVERY Cog tool call: - -| Tool | Print | -|------|-------| -| `cog_recall` | `Querying Cog...` | -| `cog_learn` | `Recording to Cog...` | -| `cog_associate` | `Linking concepts...` | -| `cog_update` | `Updating engram...` | -| `cog_trace` | `Tracing connections...` | -| `cog_connections` | `Exploring connections...` | -| `cog_unlink` | `Removing link...` | -| `cog_list_short_term` | `Listing short-term memories...` | -| `cog_reinforce` | `Reinforcing memory...` | -| `cog_flush` | `Flushing invalid memory...` | -| `cog_verify` | `Verifying synapse...` | -| `cog_stale` | `Listing stale synapses...` | - ---- - -## Tools Reference - -| Tool | Purpose | -|------|---------| -| `cog_recall` | Search with spreading activation | -| `cog_learn` | Create memory with **chains** (sequential) or associations (hub) | -| `cog_get` | Retrieve engram by ID | -| `cog_associate` | Link two existing concepts | -| `cog_trace` | Find paths between concepts | -| `cog_update` | Modify engram term/definition | -| `cog_unlink` | Remove synapse | -| `cog_connections` | List engram connections | -| `cog_bootstrap` | Exploration prompt for empty brains | -| `cog_list_short_term` | List pending consolidations | -| `cog_reinforce` | Convert short-term to long-term | -| `cog_flush` | Delete invalid short-term memory | -| `cog_verify` | Confirm synapse is still accurate | -| `cog_stale` | List synapses needing verification | - ---- - -## Querying Rules - -### Before exploring code, ALWAYS query Cog first - -Even for "trivial" tasks. The 2-second query may reveal gotchas, prior solutions, or context that changes your approach. - -### Query Reformulation (Critical for Recall) - -Before calling `cog_recall`, **transform your query from question-style to definition-style**. You are an LLM -- use that capability to bridge the vocabulary gap between how users ask questions and how knowledge is stored. - -#### Think like a definition, not a question - -| User Intent | Don't Query | Do Query | -|-------------|-------------|----------| -| "How do I handle stale data?" | `"handle stale data"` | `"cache invalidation event-driven TTL expiration data freshness"` | -| "Why does auth break after a while?" | `"auth breaks"` | `"token expiration refresh timing session timeout JWT lifecycle"` | -| "Where should validation go?" | `"where validation"` | `"input validation system boundaries sanitization defense in depth"` | - -#### The reformulation process - -1. **Identify the concept** -- What is the user actually asking about? -2. **Generate canonical terms** -- What would an engram about this be titled? -3. **Add related terminology** -- What words would the DEFINITION use? -4. **Include synonyms** -- What other terms describe the same thing? - -#### Example transformation - -``` -User asks: "Why is the payment service sometimes charging twice?" - -Your thinking: -- Concept: duplicate charges, idempotency -- Canonical terms: "idempotency", "duplicate prevention", "payment race condition" -- Definition words: "idempotent", "transaction", "mutex", "lock", "retry" -- Synonyms: "double charge", "duplicate transaction" - -Query: "payment idempotency duplicate transaction race condition mutex retry" -``` - -### Query with specific keywords - -| Task Type | Understand First | Then Query With | -|-----------|------------------|-----------------| -| Bug fix | Error message, symptoms | `"canonical error name component pattern race condition"` | -| Feature | User's description | `"domain terms design patterns architectural concepts"` | -| Test fix | Read the test file | `"API names assertion patterns test utilities"` | -| Architecture | System area | `"component relationships boundaries dependencies"` | - -**Bad:** `"authentication"` (too vague) -**Good:** `"JWT refresh token expiration session lifecycle OAuth flow"` (definition-style) - -### Use Cog results - -- Follow paths Cog reveals -- Read components Cog mentions first -- Heed gotchas Cog warns about -- If Cog is wrong, correct it immediately with `cog_update` - ---- - -## Recording Rules - -### CRITICAL: Chains vs Associations - -**Before recording, ask: Is this sequential or hub-shaped?** - -| Structure | Use | Example | -|-----------|-----|---------| -| **Sequential** (A -> B -> C) | `chain_to` | Technology enables Pattern enables Feature | -| **Hub** (A, B, C all connect to X) | `associations` | Meeting connects to Participants, Outcomes | - -**Default to chains** for: -- Technology dependencies (DB -> ORM -> API) -- Causal sequences (Cause -> Effect -> Consequence) -- Architectural decisions (ADR -> Technology -> Feature) -- Enabling relationships (Infrastructure -> enables -> Capability) -- Reasoning paths (Premise -> implies -> Conclusion) - -**Use associations** for: -- Hub/star patterns (one thing connects to many unrelated things) -- Linking to existing concepts in the graph -- Multi-party contexts (meetings, decisions with stakeholders) - -### Chain Example (PREFERRED for dependencies) - -``` -cog_learn({ - "term": "PostgreSQL", - "definition": "Relational database with ACID guarantees", - "chain_to": [ - {"term": "Ecto ORM", "definition": "Elixir database wrapper with changesets", "predicate": "enables"}, - {"term": "Phoenix Contexts", "definition": "Business logic boundaries in Phoenix", "predicate": "enables"} - ] -}) -``` - -Creates: PostgreSQL ->[enables]-> Ecto ORM ->[enables]-> Phoenix Contexts - -### Association Example (for hubs) - -``` -cog_learn({ - "term": "Auth Review 2024-01-20", - "definition": "Decided JWT with refresh tokens. Rejected session cookies.", - "associations": [ - {"target": "JWT Pattern", "predicate": "leads_to"}, - {"target": "Session Cookies", "predicate": "contradicts"}, - {"target": "Mobile Team", "predicate": "is_component_of"} - ] -}) -``` - -Creates hub: JWT Pattern <-[leads_to]<- Auth Review ->[contradicts]-> Session Cookies - ---- - -### When to record (during work) - -At these checkpoints, ask: *"What did I just learn that I didn't know 5 minutes ago?"* - -| Checkpoint | Record | -|------------|--------| -| After identifying root cause | Why it was broken | -| After reading surprising code | The non-obvious behavior | -| After a failed attempt | Why it didn't work | -| Before implementing fix | The insight (freshest now) | -| After discovering connection | The relationship | -| After a meeting or decision | The context hub linking participants and outcomes | -| After researching/exploring architecture | System limits, configuration points, component boundaries | - -**Record immediately.** Don't wait until task end -- you'll forget details. - -### Before calling `cog_learn` - -1. **Decide: chain or hub?** (see above) -2. **For chains**: Build the sequence of steps with `chain_to` -3. **For hubs**: Identify association targets from source material or Cog query - -**Skip the query when:** -- Source material explicitly names related concepts (ADRs, documentation, structured data) -- You already know target terms from conversation context -- The insight references specific concepts by name - -**Query first when:** -- Recording an insight and unsure what it relates to -- Source is vague about connections -- Exploring a new domain with unknown existing concepts - -### After calling `cog_learn` - -The operation is complete. **Do NOT verify your work by:** -- Calling `cog_recall` to check the engram exists -- Calling `cog_connections` to verify associations were created -- Calling `cog_trace` to see if paths formed - -Trust the response confirmation. Verification wastes turns and adds no value -- if the operation failed, you'll see an error. - -### Recording Efficiency - -**One operation = one tool call.** Use `chain_to` for sequences, `associations` for hubs. - -**Never** follow `cog_learn` with separate `cog_associate` calls -- put all relationships in the original call. - -### Writing good engrams - -**Terms (2-5 words):** -- "Session Token Refresh Timing" -- "Why We Chose PostgreSQL" -- NOT "Architecture" (too broad) -- NOT "Project Overview" (super-hub) - -**Definitions (1-3 sentences):** -1. What it is -2. Why it matters / consequences -3. Related keywords for search - -**Never create super-hubs** -- engrams so generic everything connects to them (e.g., "Overview", "Main System"). They pollute search results. - -### Relationship predicates - -| Predicate | Meaning | Best for | Use in | -|-----------|---------|----------|--------| -| `enables` | A makes B possible | Tech dependencies | **chain_to** | -| `requires` | A is prerequisite for B | Dependencies | **chain_to** | -| `implies` | If A then B | Logical consequences | **chain_to** | -| `leads_to` | A flows to B | Outcomes, consequences | **chain_to** | -| `precedes` | A comes before B | Sequencing, timelines | **chain_to** | -| `derived_from` | A is based on B | Origins | **chain_to** | -| `contradicts` | A and B mutually exclusive | Rejected alternatives | associations | -| `is_component_of` | A is part of B | Parts to whole | associations | -| `contains` | A includes B | Whole to parts | associations | -| `example_of` | A demonstrates pattern B | Instances of patterns | associations | -| `generalizes` | A is broader than B | Abstract concepts | associations | -| `supersedes` | A replaces B | Deprecations | associations | -| `similar_to` | A and B are closely related | Related approaches | associations | -| `contrasts_with` | A is alternative to B | Different approaches | associations | -| `related_to` | General link (use sparingly) | When nothing else fits | associations | - -**Chain predicates** (`enables`, `requires`, `implies`, `leads_to`, `precedes`, `derived_from`) express **flow** -- use them in `chain_to` to build traversable paths. - -### Modeling Complex Contexts (Hub Node Pattern) - -Synapses are binary (one source, one target). For multi-party relationships, use a **hub engram** connecting all participants. - -#### When to use hub nodes - -| Scenario | Hub Example | Connected Concepts | -|----------|-------------|-------------------| -| Meeting with outcomes | "Q1 Planning 2024-01" | Participants, decisions | -| Decision with stakeholders | "Decision: Adopt GraphQL" | Pros, cons, voters | -| Feature with components | "User Auth Feature" | OAuth, session, UI | -| Incident with timeline | "2024-01 Payment Outage" | Cause, systems, fix | - ---- - -## Consolidation (MANDATORY) - -**Every task must end with consolidation.** Short-term memories decay in 24 hours. - -### After work is complete: - -``` -cog_list_short_term({"limit": 20}) -``` - -For each memory: -- **Valid and useful?** -> `cog_reinforce` (makes permanent) -- **Wrong or not useful?** -> `cog_flush` (deletes) - -### When to reinforce immediately - -- Insights from code you just wrote (you know it's correct) -- Gotchas you just hit and fixed -- Patterns you just applied successfully - -### When to wait for validation - -- Hypotheses about why something is broken -- Assumptions about unfamiliar code -- Solutions you haven't tested - ---- - -## Verification (Prevents Staleness) - -Synapses decay if not verified as still semantically accurate. - -### When to verify - -- After using `cog_trace` and confirming paths are correct -- When reviewing `cog_connections` and relationships hold -- After successfully using knowledge from a synapse - -### Staleness levels - -| Level | Months Unverified | Score | Behavior | -|-------|-------------------|-------|----------| -| Fresh | < 3 | 0.0-0.49 | Normal | -| Warning | 3-6 | 0.5-0.79 | Appears in `cog_stale` | -| Critical | 6+ | 0.8-0.99 | Penalty in path scoring | -| Deprecated | 12+ | 1.0 | Excluded from spreading activation | - -### Periodic maintenance - -Run `cog_stale({"level": "all"})` periodically to review relationships that may have become outdated. For each stale synapse: - -- **Still accurate?** -> `cog_verify` to reset staleness -- **No longer true?** -> `cog_unlink` to remove - ---- - -## Validation & Correction - -### Cog is hints, not truth - -Always verify against current code. If Cog is wrong: - -| Scenario | Action | -|----------|--------| -| Minor inaccuracy | `cog_update` to fix | -| Pattern changed significantly | Unlink old, create new engram | -| Completely obsolete | Update to note "DEPRECATED: [reason]" | - ---- - -## Subagents - -Subagents MUST query Cog before exploring. Same rules apply: -1. Understand task -2. **Reformulate query to definition-style** -3. Query Cog with reformulated keywords -4. Wait for results -5. Then explore - ---- - -## Summary Reporting - -Only mention Cog when relevant: - -| Condition | Include | -|-----------|---------| -| Cog helped | `**Cog helped by:** [specific value]` | -| Memories created | `**Recorded to Cog:** [term names]` | -| Cog not used | Nothing (don't mention Cog) | -| Cog queried but unhelpful | Don't mention the empty query, but **still record** new knowledge you discovered through exploration | - ---- - -## Never Store - -- Passwords, API keys, tokens, secrets -- SSH/PGP keys, certificates -- Connection strings with credentials -- PII (emails, SSNs, credit cards) -- `.env` file contents - -Server auto-rejects sensitive content. - ---- - -## Limitations - -- **No engram deletion** -- use `cog_update` or `cog_unlink` -- **No multi-query** -- chain manually -- **One synapse per direction** -- repeat calls strengthen existing link - ---- - -## Spreading Activation - -`cog_recall` returns: -1. **Seeds** -- direct matches -2. **Paths** -- engrams connecting seeds (built from chains!) -3. **Synapses** -- relationships along paths - -This surfaces the "connective tissue" between results. **Chains create these traversable paths.**