Compare commits
6 Commits
c1bb006292
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| 09cbb308d2 | |||
| c120b3d4d2 | |||
| 3381945cea | |||
| d12aabdccc | |||
| d38a348a06 | |||
| 42873f4d2d |
18
flake.lock
generated
18
flake.lock
generated
@@ -495,6 +495,23 @@
|
|||||||
"type": "github"
|
"type": "github"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
"openusage": {
|
||||||
|
"flake": false,
|
||||||
|
"locked": {
|
||||||
|
"lastModified": 1770543295,
|
||||||
|
"narHash": "sha256-DvgEPZhFm06igalUPgnQ8VLkl0gk/3rm+lbEJ2/s7gM=",
|
||||||
|
"owner": "robinebers",
|
||||||
|
"repo": "openusage",
|
||||||
|
"rev": "22a7bd5f7856397400e60dd787ad82b23c763969",
|
||||||
|
"type": "github"
|
||||||
|
},
|
||||||
|
"original": {
|
||||||
|
"owner": "robinebers",
|
||||||
|
"ref": "v0.5.1",
|
||||||
|
"repo": "openusage",
|
||||||
|
"type": "github"
|
||||||
|
}
|
||||||
|
},
|
||||||
"overseer": {
|
"overseer": {
|
||||||
"flake": false,
|
"flake": false,
|
||||||
"locked": {
|
"locked": {
|
||||||
@@ -526,6 +543,7 @@
|
|||||||
"nixpkgs": "nixpkgs_2",
|
"nixpkgs": "nixpkgs_2",
|
||||||
"nixvim": "nixvim",
|
"nixvim": "nixvim",
|
||||||
"nono": "nono",
|
"nono": "nono",
|
||||||
|
"openusage": "openusage",
|
||||||
"overseer": "overseer",
|
"overseer": "overseer",
|
||||||
"sops-nix": "sops-nix",
|
"sops-nix": "sops-nix",
|
||||||
"zjstatus": "zjstatus"
|
"zjstatus": "zjstatus"
|
||||||
|
|||||||
@@ -48,6 +48,10 @@
|
|||||||
url = "github:dmmulroy/overseer";
|
url = "github:dmmulroy/overseer";
|
||||||
flake = false;
|
flake = false;
|
||||||
};
|
};
|
||||||
|
openusage = {
|
||||||
|
url = "github:robinebers/openusage/v0.5.1";
|
||||||
|
flake = false;
|
||||||
|
};
|
||||||
};
|
};
|
||||||
|
|
||||||
outputs = inputs @ {flake-parts, ...}:
|
outputs = inputs @ {flake-parts, ...}:
|
||||||
|
|||||||
132
overlays/openusage.nix
Normal file
132
overlays/openusage.nix
Normal file
@@ -0,0 +1,132 @@
|
|||||||
|
{inputs}: final: prev: let
|
||||||
|
version = "0.5.1";
|
||||||
|
in {
|
||||||
|
openusage =
|
||||||
|
prev.rustPlatform.buildRustPackage (finalAttrs: {
|
||||||
|
pname = "openusage";
|
||||||
|
inherit version;
|
||||||
|
|
||||||
|
src = inputs.openusage;
|
||||||
|
|
||||||
|
cargoRoot = "src-tauri";
|
||||||
|
cargoLock = {
|
||||||
|
lockFile = "${inputs.openusage}/src-tauri/Cargo.lock";
|
||||||
|
outputHashes = {
|
||||||
|
"tauri-nspanel-2.1.0" = "sha256-PLACEHOLDER";
|
||||||
|
"tauri-plugin-aptabase-1.0.0" = "sha256-PLACEHOLDER";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
buildAndTestSubdir = finalAttrs.cargoRoot;
|
||||||
|
|
||||||
|
node_modules =
|
||||||
|
prev.stdenv.mkDerivation {
|
||||||
|
inherit (finalAttrs) src version;
|
||||||
|
pname = "${finalAttrs.pname}-node_modules";
|
||||||
|
|
||||||
|
impureEnvVars =
|
||||||
|
prev.lib.fetchers.proxyImpureEnvVars
|
||||||
|
++ [
|
||||||
|
"GIT_PROXY_COMMAND"
|
||||||
|
"SOCKS_SERVER"
|
||||||
|
];
|
||||||
|
|
||||||
|
nativeBuildInputs = [
|
||||||
|
prev.bun
|
||||||
|
prev.writableTmpDirAsHomeHook
|
||||||
|
];
|
||||||
|
|
||||||
|
dontConfigure = true;
|
||||||
|
dontFixup = true;
|
||||||
|
dontPatchShebangs = true;
|
||||||
|
|
||||||
|
buildPhase = ''
|
||||||
|
runHook preBuild
|
||||||
|
|
||||||
|
export BUN_INSTALL_CACHE_DIR=$(mktemp -d)
|
||||||
|
|
||||||
|
bun install \
|
||||||
|
--no-progress \
|
||||||
|
--frozen-lockfile \
|
||||||
|
--ignore-scripts
|
||||||
|
|
||||||
|
runHook postBuild
|
||||||
|
'';
|
||||||
|
|
||||||
|
installPhase = ''
|
||||||
|
runHook preInstall
|
||||||
|
cp -R ./node_modules $out
|
||||||
|
runHook postInstall
|
||||||
|
'';
|
||||||
|
|
||||||
|
outputHash = "sha256-PLACEHOLDER";
|
||||||
|
outputHashMode = "recursive";
|
||||||
|
};
|
||||||
|
|
||||||
|
nativeBuildInputs = [
|
||||||
|
prev.cargo-tauri.hook
|
||||||
|
prev.rustPlatform.bindgenHook
|
||||||
|
prev.bun
|
||||||
|
prev.nodejs
|
||||||
|
prev.pkg-config
|
||||||
|
prev.makeBinaryWrapper
|
||||||
|
];
|
||||||
|
|
||||||
|
buildInputs =
|
||||||
|
prev.lib.optionals prev.stdenv.isDarwin (
|
||||||
|
with prev.darwin.apple_sdk.frameworks; [
|
||||||
|
AppKit
|
||||||
|
CoreFoundation
|
||||||
|
CoreServices
|
||||||
|
Security
|
||||||
|
WebKit
|
||||||
|
]
|
||||||
|
);
|
||||||
|
|
||||||
|
# Disable updater artifact generation — we don't have signing keys.
|
||||||
|
tauriConf = builtins.toJSON {bundle.createUpdaterArtifacts = false;};
|
||||||
|
passAsFile = ["tauriConf"];
|
||||||
|
preBuild = ''
|
||||||
|
tauriBuildFlags+=(
|
||||||
|
"--config"
|
||||||
|
"$tauriConfPath"
|
||||||
|
)
|
||||||
|
'';
|
||||||
|
|
||||||
|
configurePhase = ''
|
||||||
|
runHook preConfigure
|
||||||
|
|
||||||
|
# Copy pre-fetched node_modules
|
||||||
|
cp -R ${finalAttrs.node_modules} node_modules/
|
||||||
|
chmod -R u+rw node_modules
|
||||||
|
chmod -R u+x node_modules/.bin
|
||||||
|
patchShebangs node_modules
|
||||||
|
|
||||||
|
export HOME=$TMPDIR
|
||||||
|
export PATH="$PWD/node_modules/.bin:$PATH"
|
||||||
|
|
||||||
|
# Bundle plugins (copy from plugins/ to src-tauri/resources/bundled_plugins/)
|
||||||
|
${prev.nodejs}/bin/node copy-bundled.cjs
|
||||||
|
|
||||||
|
runHook postConfigure
|
||||||
|
'';
|
||||||
|
|
||||||
|
env = {
|
||||||
|
OPENSSL_NO_VENDOR = true;
|
||||||
|
};
|
||||||
|
|
||||||
|
doCheck = false;
|
||||||
|
|
||||||
|
postInstall =
|
||||||
|
prev.lib.optionalString prev.stdenv.isDarwin ''
|
||||||
|
makeWrapper $out/Applications/OpenUsage.app/Contents/MacOS/OpenUsage $out/bin/openusage
|
||||||
|
'';
|
||||||
|
|
||||||
|
meta = {
|
||||||
|
description = "Track all your AI coding subscriptions in one place";
|
||||||
|
homepage = "https://github.com/robinebers/openusage";
|
||||||
|
license = prev.lib.licenses.mit;
|
||||||
|
platforms = prev.lib.platforms.darwin;
|
||||||
|
mainProgram = "openusage";
|
||||||
|
};
|
||||||
|
});
|
||||||
|
}
|
||||||
@@ -17,7 +17,7 @@
|
|||||||
model = "anthropic/claude-opus-4-6";
|
model = "anthropic/claude-opus-4-6";
|
||||||
small_model = "opencode/minimax-m2.1";
|
small_model = "opencode/minimax-m2.1";
|
||||||
theme = "catppuccin";
|
theme = "catppuccin";
|
||||||
plugin = ["opencode-anthropic-auth"];
|
plugin = ["oh-my-opencode" "opencode-anthropic-auth"];
|
||||||
keybinds = {
|
keybinds = {
|
||||||
leader = "ctrl+o";
|
leader = "ctrl+o";
|
||||||
};
|
};
|
||||||
@@ -36,7 +36,7 @@
|
|||||||
model = "anthropic/claude-opus-4-6";
|
model = "anthropic/claude-opus-4-6";
|
||||||
};
|
};
|
||||||
explore = {
|
explore = {
|
||||||
model = "opencode/minimax-m2.1";
|
model = "anthropic/claude-haiku-4-5";
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
instructions = [
|
instructions = [
|
||||||
@@ -50,6 +50,14 @@
|
|||||||
};
|
};
|
||||||
};
|
};
|
||||||
mcp = {
|
mcp = {
|
||||||
|
cog = {
|
||||||
|
enabled = true;
|
||||||
|
type = "remote";
|
||||||
|
url = "https://trycog.ai/mcp";
|
||||||
|
headers = {
|
||||||
|
Authorization = "Bearer {env:COG_API_TOKEN}";
|
||||||
|
};
|
||||||
|
};
|
||||||
context7 = {
|
context7 = {
|
||||||
enabled = true;
|
enabled = true;
|
||||||
type = "remote";
|
type = "remote";
|
||||||
@@ -66,7 +74,7 @@
|
|||||||
command = ["bunx" "opensrc-mcp"];
|
command = ["bunx" "opensrc-mcp"];
|
||||||
};
|
};
|
||||||
overseer = {
|
overseer = {
|
||||||
enabled = true;
|
enabled = false;
|
||||||
type = "local";
|
type = "local";
|
||||||
command = ["${pkgs.overseer}/bin/os" "mcp"];
|
command = ["${pkgs.overseer}/bin/os" "mcp"];
|
||||||
};
|
};
|
||||||
@@ -91,5 +99,14 @@
|
|||||||
source = ./opencode/tool;
|
source = ./opencode/tool;
|
||||||
recursive = true;
|
recursive = true;
|
||||||
};
|
};
|
||||||
|
"opencode/oh-my-opencode.json".text =
|
||||||
|
builtins.toJSON {
|
||||||
|
"$schema" = "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json";
|
||||||
|
disabled_mcps = ["websearch" "context7" "grep_app"];
|
||||||
|
git_master = {
|
||||||
|
commit_footer = false;
|
||||||
|
include_co_authored_by = false;
|
||||||
|
};
|
||||||
|
};
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,94 +0,0 @@
|
|||||||
---
|
|
||||||
description: Senior engineering advisor for code reviews, architecture decisions, complex debugging, and planning. Invoke when you need deeper analysis before acting — reviews, trade-offs, debugging race conditions, planning refactors. Prompt with precise problem + files. Ask for concrete outcomes.
|
|
||||||
mode: subagent
|
|
||||||
model: opencode/gpt-5.2-codex
|
|
||||||
options:
|
|
||||||
thinking:
|
|
||||||
type: enabled
|
|
||||||
budgetTokens: 31999
|
|
||||||
permission:
|
|
||||||
"*": deny
|
|
||||||
read: allow
|
|
||||||
grep: allow
|
|
||||||
glob: allow
|
|
||||||
webfetch: allow
|
|
||||||
opensrc_execute: allow
|
|
||||||
context7_resolve-library-id: allow
|
|
||||||
context7_query-docs: allow
|
|
||||||
grep_app_searchGitHub: allow
|
|
||||||
lsp: allow
|
|
||||||
---
|
|
||||||
|
|
||||||
You are the Oracle - an expert AI advisor with advanced reasoning capabilities.
|
|
||||||
|
|
||||||
Your role is to provide high-quality technical guidance, code reviews, architectural advice, and strategic planning for software engineering tasks.
|
|
||||||
|
|
||||||
You are a subagent inside an AI coding system, called when the main agent needs a smarter, more capable model. You are invoked in a zero-shot manner - no one can ask you follow-up questions or provide follow-up answers.
|
|
||||||
|
|
||||||
## Key Responsibilities
|
|
||||||
|
|
||||||
- Analyze code and architecture patterns
|
|
||||||
- Provide specific, actionable technical recommendations
|
|
||||||
- Plan implementations and refactoring strategies
|
|
||||||
- Answer deep technical questions with clear reasoning
|
|
||||||
- Suggest best practices and improvements
|
|
||||||
- Identify potential issues and propose solutions
|
|
||||||
|
|
||||||
## Operating Principles (Simplicity-First)
|
|
||||||
|
|
||||||
1. **Default to simplest viable solution** that meets stated requirements
|
|
||||||
2. **Prefer minimal, incremental changes** that reuse existing code, patterns, and dependencies
|
|
||||||
3. **Optimize for maintainability and developer time** over theoretical scalability
|
|
||||||
4. **Apply YAGNI and KISS** - avoid premature optimization
|
|
||||||
5. **One primary recommendation** - offer alternatives only if trade-offs are materially different
|
|
||||||
6. **Calibrate depth to scope** - brief for small tasks, deep only when required
|
|
||||||
7. **Stop when "good enough"** - note signals that would justify revisiting
|
|
||||||
|
|
||||||
## Effort Estimates
|
|
||||||
|
|
||||||
Include rough effort signal when proposing changes:
|
|
||||||
- **S** (<1 hour) - trivial, single-location change
|
|
||||||
- **M** (1-3 hours) - moderate, few files
|
|
||||||
- **L** (1-2 days) - significant, cross-cutting
|
|
||||||
- **XL** (>2 days) - major refactor or new system
|
|
||||||
|
|
||||||
## Response Format
|
|
||||||
|
|
||||||
Keep responses concise and action-oriented. For straightforward questions, collapse sections as appropriate:
|
|
||||||
|
|
||||||
### 1. TL;DR
|
|
||||||
1-3 sentences with the recommended simple approach.
|
|
||||||
|
|
||||||
### 2. Recommendation
|
|
||||||
Numbered steps or short checklist. Include minimal diffs/snippets only as needed.
|
|
||||||
|
|
||||||
### 3. Rationale
|
|
||||||
Brief justification. Mention why alternatives are unnecessary now.
|
|
||||||
|
|
||||||
### 4. Risks & Guardrails
|
|
||||||
Key caveats and mitigations.
|
|
||||||
|
|
||||||
### 5. When to Reconsider
|
|
||||||
Concrete triggers that justify a more complex design.
|
|
||||||
|
|
||||||
### 6. Advanced Path (optional)
|
|
||||||
Brief outline only if relevant and trade-offs are significant.
|
|
||||||
|
|
||||||
## Tool Usage
|
|
||||||
|
|
||||||
You have read-only access: read, grep, glob, LSP, webfetch, opensrc, context7, grep_app.
|
|
||||||
Use them freely to verify assumptions and gather context:
|
|
||||||
- **opensrc**: Fetch and explore third-party package/repo source code
|
|
||||||
- **context7**: Look up library documentation and API examples (resolve-library-id first, then query-docs)
|
|
||||||
- **grep_app**: Search public GitHub repos for real-world usage patterns
|
|
||||||
Your extended thinking enables deep analysis - leverage it fully.
|
|
||||||
|
|
||||||
## Guidelines
|
|
||||||
|
|
||||||
- Investigate thoroughly; report concisely - focus on highest-leverage insights
|
|
||||||
- For planning tasks, break down into minimal steps that achieve the goal incrementally
|
|
||||||
- Justify recommendations briefly - avoid long speculative exploration
|
|
||||||
- If the request is ambiguous, state your interpretation explicitly before answering
|
|
||||||
- If unanswerable from available context, say so directly
|
|
||||||
|
|
||||||
**IMPORTANT:** Only your last message is returned to the main agent and displayed to the user. Make it comprehensive yet focused, with a clear, simple recommendation that enables immediate action.
|
|
||||||
406
profiles/opencode/skill/cog/SKILL.md
Normal file
406
profiles/opencode/skill/cog/SKILL.md
Normal file
@@ -0,0 +1,406 @@
|
|||||||
|
---
|
||||||
|
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.**
|
||||||
@@ -52,6 +52,7 @@ with pkgs;
|
|||||||
alcove
|
alcove
|
||||||
dockutil
|
dockutil
|
||||||
mas
|
mas
|
||||||
|
openusage
|
||||||
raycast
|
raycast
|
||||||
tailscale
|
tailscale
|
||||||
xcodes
|
xcodes
|
||||||
|
|||||||
Reference in New Issue
Block a user