diff --git a/.cursor/mcp.json b/.cursor/mcp.json index 97acdea..37bb648 100644 --- a/.cursor/mcp.json +++ b/.cursor/mcp.json @@ -1,7 +1,7 @@ { - "mcpServers": { - "clawql": { - "url": "http://localhost:8080/mcp" - } + "mcpServers": { + "clawql": { + "url": "http://127.0.0.1/mcp" } -} \ No newline at end of file + } +} diff --git a/.cursor/mcp.json.example b/.cursor/mcp.json.example index bee0150..37bb648 100644 --- a/.cursor/mcp.json.example +++ b/.cursor/mcp.json.example @@ -1,7 +1,7 @@ { "mcpServers": { "clawql": { - "url": "http://localhost:8080/mcp" + "url": "http://127.0.0.1/mcp" } } } diff --git a/.cursor/rules/clawql-vault-memory.mdc b/.cursor/rules/clawql-vault-memory.mdc index 2b9eaa4..34e3ba1 100644 --- a/.cursor/rules/clawql-vault-memory.mdc +++ b/.cursor/rules/clawql-vault-memory.mdc @@ -7,23 +7,10 @@ alwaysApply: true When **ClawQL MCP** is available, use it deliberately: +- **`call_mcp_tool`**: Use server **`user-clawql`** if ClawQL is configured in **`~/.cursor/mcp.json`**, or **`workspace-clawql`** if it is only in **`.cursor/mcp.json`** in the repo. The `mcpServers` key remains **`clawql`** in JSON; Cursor prepends **`user-`** / **`workspace-`** for the agent API. Bare **`clawql`** is not accepted there. - **`memory_recall`**: At the start of non-trivial work, or when the user references past decisions, the vault, or missing context. Use a concrete `query`; keep `limit` reasonable; raise **`maxDepth`** when graph context matters. - **`memory_ingest`**: After important outcomes—decisions, debugging conclusions, env/setup notes, API contracts, user preferences, or links between topics. Prefer structured **`insights`**; put verbatim logs in **`toolOutputs`**; use **`wikilinks`** for the Obsidian graph; reuse **`title`** with **`append: true`** (default) to extend the same page. **Thorough ingests** (rich structure, tagging in prose, wikilink strategy, session threading, anti-patterns): read and apply the project skill [**clawql-vault-memory**](../skills/clawql-vault-memory/SKILL.md). -Do not store secrets, credentials, or private keys. If vault tools fail (path unset), say so briefly and continue without blocking the task. - -## `call_mcp_tool` (agent API) — server name - -**You cannot use the key from `.editor/mcp.json`** (e.g. `"clawql"`). editor agent’s agent bridge registers MCP under a **generated `serverIdentifier`** that you do **not** control and that **does not match** the JSON key. Guessing names like `user-…` or `workspace-…` is unreliable—identifiers in the wild include forms like **`project-0--clawql`**. - -**Always** pass the string from **`serverIdentifier`** inside: - -`~/.editor/projects//mcps/<…-clawql>/SERVER_METADATA.json` - -For this repo’s current layout, that file is typically: - -`~/.editor/projects/Users-danielsmith-danielsmithdevelopment-github-io/mcps/project-0-danielsmithdevelopment.github.io-clawql/SERVER_METADATA.json` - -If tools fail with “server does not exist”: **do not** argue with the user about MCP config—**read that JSON** (or run `find ~/.editor/projects -path '*mcps*clawql*' -name SERVER_METADATA.json 2>/dev/null | head -1`) and use the **`serverIdentifier`** value exactly. Re-check after renaming the repo folder or moving the project, because the slug in the path can change. +Do not store secrets, credentials, or private keys. **`memory_ingest`** / **`memory_recall`** are registered by default; **`CLAWQL_ENABLE_MEMORY=0`** hides them. A writable vault path is required for real I/O. If vault tools are missing or fail, say so briefly and continue without blocking the task. diff --git a/.cursor/rules/git-no-direct-main-push-without-explicit-user-consent.mdc b/.cursor/rules/git-no-direct-main-push-without-explicit-user-consent.mdc new file mode 100644 index 0000000..1c2b79f --- /dev/null +++ b/.cursor/rules/git-no-direct-main-push-without-explicit-user-consent.mdc @@ -0,0 +1,19 @@ +--- +description: Never push directly to main/master without explicit same-message user request +alwaysApply: true +--- + +# Git Safety: No Direct Main Push + +- Never run `git push` to `main` or `master` unless the user explicitly asks for it in the current message. +- If the user asks to "commit", "create PR", or "push" without naming a branch, do not push to `main`/`master`; ask which branch/PR flow they want. +- Before any push command, print the exact target (`remote`, `branch`) in the chat and require explicit confirmation when target is `main`/`master`. +- Prefer branch + PR flow for all agent-authored changes. + +## Required guard + +Before executing a push: + +1. Run `git rev-parse --abbrev-ref HEAD`. +2. If branch is `main` or `master` and there is no explicit same-message user instruction to push main/master, stop and ask. +3. Never infer consent from prior messages. diff --git a/.cursor/rules/git-pr-merge-wait-ci.mdc b/.cursor/rules/git-pr-merge-wait-ci.mdc index d76ece3..98c63eb 100644 --- a/.cursor/rules/git-pr-merge-wait-ci.mdc +++ b/.cursor/rules/git-pr-merge-wait-ci.mdc @@ -14,7 +14,3 @@ When merging pull requests (GitHub / `gh pr merge`): - **Only then** run `gh pr merge --merge` (merge-after-green). Prefer this sequence over trusting `--auto` unless you have verified branch protection blocks merge until required checks pass. If branch protection blocks merge until green, do not bypass it. Do not assume checks are optional. - -## Commit messages — no editor agent branding - -Do **not** add trailers such as **`Made-with: editor agent`**, **`Co-authored-by: editor agent`**, or similar tool-generated attribution to commits in this repository. If an editor or hook injects them, remove before `git commit` / amend before push. diff --git a/.cursor/skills/clawql-audit-workflows/SKILL.md b/.cursor/skills/clawql-audit-workflows/SKILL.md new file mode 100644 index 0000000..a543d91 --- /dev/null +++ b/.cursor/skills/clawql-audit-workflows/SKILL.md @@ -0,0 +1,25 @@ +--- +name: clawql-audit-workflows +description: >- + Workflow recipes for the ClawQL MCP audit tool. The audit tool is ClawQL Core + (always registered — no CLAWQL_ENABLE_AUDIT); this skill is optional guidance for + append/list/clear patterns during multi-step runs. +--- + +# ClawQL audit workflows + +## When to apply + +- You want structured **`audit.append`** / **`audit.list`** breadcrumbs during a workflow (the tool is already available on every ClawQL MCP server). + +## Workflow + +1. `audit.append` at key milestones. +2. Use consistent category/action names. +3. Add `correlationId` for multi-step runs. +4. `audit.list` for active debugging. +5. `memory_ingest` final durable summary. + +## Guardrail + +- Audit is not durable/compliance storage. diff --git a/.cursor/skills/clawql-cache-workflows/SKILL.md b/.cursor/skills/clawql-cache-workflows/SKILL.md new file mode 100644 index 0000000..fc956f7 --- /dev/null +++ b/.cursor/skills/clawql-cache-workflows/SKILL.md @@ -0,0 +1,24 @@ +--- +name: clawql-cache-workflows +description: Use the cache MCP tool (ClawQL Core, always on) as ephemeral scratch state during active sessions. +--- + +# ClawQL cache workflows + +The **`cache`** tool is **ClawQL Core** — always registered ([#75](https://github.com/danielsmithdevelopment/ClawQL/issues/75), **closed**). It is not optional; do not confuse with vault **`memory_*`**. + +## When to apply + +- You need temporary handoff state during a single run. + +## Workflow + +1. `cache.set` for short-lived keys. +2. `cache.get` during step transitions. +3. `cache.list/search` for inspection. +4. `cache.delete` when done. + +## Boundary + +- Cache is ephemeral process-local state. +- Use `memory_ingest` for durable memory. diff --git a/.cursor/skills/clawql-composed-mcp-workflows/SKILL.md b/.cursor/skills/clawql-composed-mcp-workflows/SKILL.md new file mode 100644 index 0000000..533c282 --- /dev/null +++ b/.cursor/skills/clawql-composed-mcp-workflows/SKILL.md @@ -0,0 +1,21 @@ +--- +name: clawql-composed-mcp-workflows +description: Apply proven end-to-end recipes combining search/execute, memory, notify, schedule, and optional tools. +--- + +# ClawQL composed MCP workflows + +## When to apply + +- The task spans multiple tools and needs a repeatable pattern. + +## Core recipes + +- Safe API change rollout: `search -> execute(read) -> execute(write) -> execute(read) -> memory_ingest`. +- Incident triage: `memory_recall -> search/execute -> audit -> notify -> memory_ingest`. +- Knowledge-grounded ops: `knowledge_search_onyx -> execute -> memory_ingest -> notify`. +- Synthetic monitoring: `schedule(create/trigger dry_run) -> notify -> memory_ingest`. + +## Source + +- Canonical recipe library: `docs/recipes/README.md` diff --git a/.cursor/skills/clawql-execute-workflows/SKILL.md b/.cursor/skills/clawql-execute-workflows/SKILL.md new file mode 100644 index 0000000..c2b9ab9 --- /dev/null +++ b/.cursor/skills/clawql-execute-workflows/SKILL.md @@ -0,0 +1,24 @@ +--- +name: clawql-execute-workflows +description: Execute discovered API operations safely with argument validation and post-change verification. +--- + +# ClawQL execute workflows + +## When to apply + +- You already have a valid `operationId`. +- You need real API action/output through MCP. + +## Workflow + +1. Confirm operation via `search`. +2. Build precise `args` from discovered params. +3. Optionally set `fields` to reduce payload. +4. Execute read-before-write when changing state. +5. Verify via follow-up read. + +## Notes + +- **OpenAPI/Discovery:** single-spec prefers OpenAPI→GraphQL with REST fallback; multi-spec uses REST per owning spec. +- **Native GraphQL/gRPC** (`CLAWQL_GRAPHQL_SOURCES` / `CLAWQL_GRPC_SOURCES`): `execute` uses HTTP GraphQL or gRPC unary — same `operationId` contract, different transport (see ADR 0002). diff --git a/.cursor/skills/clawql-external-ingest/SKILL.md b/.cursor/skills/clawql-external-ingest/SKILL.md new file mode 100644 index 0000000..710ad61 --- /dev/null +++ b/.cursor/skills/clawql-external-ingest/SKILL.md @@ -0,0 +1,23 @@ +--- +name: clawql-external-ingest +description: Import external markdown or URL content using ingest_external_knowledge with dry-run-first validation. +--- + +# ClawQL ingest_external_knowledge workflows + +## When to apply + +- You need to import external docs into vault-backed memory. + +## Workflow + +1. Ensure `CLAWQL_EXTERNAL_INGEST=1`. +2. Start with `dryRun: true`. +3. Validate paths/scope/content. +4. Re-run with `dryRun: false`. +5. Confirm discoverability with `memory_recall`. + +## Modes + +- `documents[]` for bulk markdown. +- `source: "url"` for URL import (`CLAWQL_EXTERNAL_INGEST_FETCH=1`). diff --git a/.cursor/skills/clawql-memory-ingest/SKILL.md b/.cursor/skills/clawql-memory-ingest/SKILL.md new file mode 100644 index 0000000..e17259f --- /dev/null +++ b/.cursor/skills/clawql-memory-ingest/SKILL.md @@ -0,0 +1,24 @@ +--- +name: clawql-memory-ingest +description: Persist durable session outcomes with memory_ingest using stable titles, append threading, and wikilinks. +--- + +# ClawQL memory_ingest workflows + +## When to apply + +- A meaningful outcome needs durable memory. +- You are ending a complex debugging or implementation thread. + +## Workflow + +1. Use stable `title` for topic continuity. +2. Add concise `insights` and decisions. +3. Add `wikilinks` to related notes. +4. Use `sessionId` and `append: true` for long-running threads. +5. Prefer `toolOutputsFile` for large artifacts. + +## Guardrails + +- Never include secrets. +- Keep raw logs in tool outputs, not insight prose. diff --git a/.cursor/skills/clawql-memory-recall/SKILL.md b/.cursor/skills/clawql-memory-recall/SKILL.md new file mode 100644 index 0000000..5184579 --- /dev/null +++ b/.cursor/skills/clawql-memory-recall/SKILL.md @@ -0,0 +1,23 @@ +--- +name: clawql-memory-recall +description: Recall relevant vault context before deep work using focused queries and graph depth controls. +--- + +# ClawQL memory_recall workflows + +## When to apply + +- Before deep tasks or decisions. +- When user references prior sessions. + +## Workflow + +1. Query with specific component/feature/error terms. +2. Start with low `limit`. +3. Increase `maxDepth` for wikilink context. +4. Raise `minScore` if noisy. +5. Summarize hits before acting. + +## Pattern + +- `memory_recall` -> work (`search`/`execute`) -> `memory_ingest`. diff --git a/.cursor/skills/clawql-notify-workflows/SKILL.md b/.cursor/skills/clawql-notify-workflows/SKILL.md new file mode 100644 index 0000000..f19e5bd --- /dev/null +++ b/.cursor/skills/clawql-notify-workflows/SKILL.md @@ -0,0 +1,21 @@ +--- +name: clawql-notify-workflows +description: Send actionable Slack milestones and failure notifications with the optional notify tool. +--- + +# ClawQL notify workflows + +## When to apply + +- Workflow state should be visible to humans in Slack. + +## Workflow + +1. Send start/failure/recovery milestones. +2. Use one thread per run (`thread_ts`). +3. Include links, owner, and next action. +4. Pair with `audit` and `memory_ingest` for traceability. + +## Message structure + +- status, workflow, identifier, next action, link(s). diff --git a/.cursor/skills/clawql-onyx-knowledge-workflows/SKILL.md b/.cursor/skills/clawql-onyx-knowledge-workflows/SKILL.md new file mode 100644 index 0000000..6201de9 --- /dev/null +++ b/.cursor/skills/clawql-onyx-knowledge-workflows/SKILL.md @@ -0,0 +1,22 @@ +--- +name: clawql-onyx-knowledge-workflows +description: Use knowledge_search_onyx to ground workflows in enterprise evidence before execution. +--- + +# ClawQL knowledge_search_onyx workflows + +## When to apply + +- Decisions/actions require enterprise-document grounding. + +## Workflow + +1. Query Onyx for relevant evidence. +2. Summarize key supporting snippets. +3. Execute downstream API actions. +4. Persist evidence summary with `memory_ingest`. +5. Notify completion as needed. + +## Guardrail + +- Treat retrieved content as evidence input, not guaranteed truth. diff --git a/.cursor/skills/clawql-ouroboros-workflows/SKILL.md b/.cursor/skills/clawql-ouroboros-workflows/SKILL.md new file mode 100644 index 0000000..d4d3b4d --- /dev/null +++ b/.cursor/skills/clawql-ouroboros-workflows/SKILL.md @@ -0,0 +1,53 @@ +--- +name: clawql-ouroboros-workflows +description: Run iterative specification-first workflows with ouroboros_* tools, lineage checks, and clear boundaries vs raw infra (kubectl/Helm). +--- + +# ClawQL ouroboros workflows + +## When to apply + +- Task requirements are **ambiguous** and need **iterative convergence** over a **Seed** (goal, acceptance criteria, ontology-shaped extraction). +- You want **traceable lineage** (`ouroboros_get_lineage_status`) across generations, not only a one-off answer. + +## What the tools **do** and **do not** do + +| Tool | Purpose | +|------|---------| +| `ouroboros_create_seed_from_document` | Turn **document text** (or pasted incident report) into a structured **Seed** (`goal`, `acceptance_criteria`, ontology fields, `metadata.seed_id`). | +| `ouroboros_run_evolutionary_loop` | Run **Wonder / Reflect / Execute / Evaluate** cycles on that Seed until `maxGenerations` or convergence. | +| `ouroboros_get_lineage_status` | Read **stored generations** for a `seed_id` (durable if Postgres-backed ouroboros DB is configured). | + +**They do not:** call `kubectl`, `helm`, SSH, or the Kubernetes API. The default **Executor** only does meaningful *ClawQL-internal* work when the Seed includes **`brownfield_context.context_references`** entries shaped as **`clawql_execute`** or **`clawql_search`** objects (see `website/src/app/ouroboros/page.mdx` § *Route hints*). If `context_references` is only plain strings (e.g. a document id), execution stays a **stub** (`"No internal tool route selected"`). + +So: **Ouroboros = spec / ontology / acceptance iteration + optional OpenAPI-routed execution.** **Infra triage = kubectl, logs, Helm values, cluster events** — run that in parallel or first when failures are scheduler- or container-exit-driven. + +## Recommended workflow (skill order) + +1. **`ouroboros_create_seed_from_document`** — Set `extractedText` to the **requirements doc**, **design notes**, or a **redacted** paste of `kubectl describe` / `logs` / events if you want a durable *seed* anchored to the incident (not a substitute for reading those logs yourself). +2. **If the task includes validating HTTP/OpenAPI behavior** — add **`context_references`** with **`clawql_search`** / **`clawql_execute`** hints (or extend the seed after step 1) so generations can drive real tool routes. +3. **`ouroboros_run_evolutionary_loop`** — Use a **small `maxGenerations`** first (e.g. 2–6); raise only if convergence is too weak. +4. **`ouroboros_get_lineage_status`** — Inspect `seed_id` for scores, execution blobs, and whether acceptance criteria passed per generation. +5. **Refine** constraints / acceptance criteria / hints and rerun when needed. +6. **`memory_ingest`** — Persist decisions, chart paths, and operator runbooks (no secrets). Link related vault titles via `wikilinks`. + +## Hybrid with Kubernetes / Helm (common case) + +When the user goal is **“fix the cluster”** (CrashLoop, `Pending`, `Insufficient memory`, chart bugs): + +1. **Do not skip** steps 1–4 if the user attached this skill: still **create a seed** from the incident summary so **lineage exists** and acceptance criteria are explicit—even when the next step is mostly `kubectl`. +2. **Run infra investigation in parallel** (or immediately): `kubectl get pods`, `describe`, `logs`, Helm `values.yaml` / templates. The **first root cause** usually lives here. +3. **Use `ouroboros_run_evolutionary_loop`** to **converge on spec-level acceptance** (e.g. “helm template validates”, “documented health checks pass”) **only if** you can express checks via **execute hints** or human-verified criteria; do not expect the loop alone to discover a bad Helm `command:` block. +4. After code or chart changes, **persist** with **`memory_ingest`** (and optional `wikilinks` to related notes such as `[[Helm full Onyx stack Docker Desktop]]`). + +## Guardrails + +- Keep **acceptance criteria** concrete and testable. +- Separate **shipped behavior** from **roadmap assumptions**. +- **Never** put tokens, kubeconfig blobs, or `OPENSEARCH_ADMIN_PASSWORD`-style values into Seeds or `memory_ingest`. + +## Further reading (repo) + +- Route hints and sample `ouroboros_run_evolutionary_loop` JSON: `website/src/app/ouroboros/page.mdx` +- Skill overview: `docs/skills/ouroboros.md` +- ADR: `docs/adr/0001-ouroboros-workflow-engine.md` diff --git a/.cursor/skills/clawql-sandbox-exec/SKILL.md b/.cursor/skills/clawql-sandbox-exec/SKILL.md new file mode 100644 index 0000000..ac172d2 --- /dev/null +++ b/.cursor/skills/clawql-sandbox-exec/SKILL.md @@ -0,0 +1,25 @@ +--- +name: clawql-sandbox-exec +description: Run isolated code snippets via sandbox_exec with safe persistence/session patterns. +--- + +# ClawQL sandbox_exec workflows + +**`CLAWQL_ENABLE_SANDBOX=1`** registers **`sandbox_exec`**. Then **unset** **`CLAWQL_SANDBOX_BACKEND`** = bridge; **`auto`** = **Seatbelt** → **Docker** → **bridge**. + +## When to apply + +- **`CLAWQL_ENABLE_SANDBOX=1`** is set and you need bridge-only, **`auto`**, or a pinned **`CLAWQL_SANDBOX_BACKEND`**. +- You want session-based state across related sandbox calls. + +## Workflow + +1. Set **`CLAWQL_SANDBOX_BACKEND`** (omit, **`auto`**, or **`bridge`** / **`macos-seatbelt`** / **`docker`**) and matching env (bridge URL + token, Docker CLI, or macOS **`sandbox-exec`**). +2. Choose `language` and minimal `code`. +3. Use `sessionId` + `persistenceMode: session` for multi-step tasks. +4. Keep `ephemeral` mode for one-off checks. + +## Guardrails + +- **`bridge`** runs remotely via the Worker; **`macos-seatbelt`** / **`docker`** run locally under Seatbelt or container isolation — not an unconstrained host shell. +- Persist outcomes with **`memory_ingest`** if needed later. diff --git a/.cursor/skills/clawql-schedule-workflows/SKILL.md b/.cursor/skills/clawql-schedule-workflows/SKILL.md new file mode 100644 index 0000000..4842217 --- /dev/null +++ b/.cursor/skills/clawql-schedule-workflows/SKILL.md @@ -0,0 +1,19 @@ +--- +name: clawql-schedule-workflows +description: Build recurring synthetic checks with schedule, validate via dry_run, and pair with notify. +--- + +# ClawQL schedule workflows + +## When to apply + +- You need persisted recurring synthetic monitoring jobs. + +## Workflow + +1. Create schedule with synthetic action. +2. Trigger with `dry_run: true`. +3. Fix assertions/targets as needed. +4. Enable recurring run. +5. Pair failure path with `notify`. +6. Record lessons via `memory_ingest`. diff --git a/.cursor/skills/clawql-search-workflows/SKILL.md b/.cursor/skills/clawql-search-workflows/SKILL.md new file mode 100644 index 0000000..dbc743b --- /dev/null +++ b/.cursor/skills/clawql-search-workflows/SKILL.md @@ -0,0 +1,24 @@ +--- +name: clawql-search-workflows +description: Use ClawQL search to discover correct operationIds before execute calls, especially in multi-provider workflows. +--- + +# ClawQL search workflows + +## When to apply + +- You know intent but not `operationId`. +- You need parameter hints before calling `execute`. +- You want discovery-only planning before any mutations. + +## Workflow + +1. Run `search` with concrete verb + domain terms. +2. Review top candidates and required params. +3. Refine query if ambiguous. +4. Pass validated `operationId` to `execute`. + +## Guardrails + +- Prefer `search`-first over guessed operation IDs. +- In complex runs, do all discovery first, then execute. diff --git a/.cursor/skills/clawql-vault-memory/SKILL.md b/.cursor/skills/clawql-vault-memory/SKILL.md index 953d49e..aa8a5c2 100644 --- a/.cursor/skills/clawql-vault-memory/SKILL.md +++ b/.cursor/skills/clawql-vault-memory/SKILL.md @@ -17,13 +17,18 @@ description: >- If **ClawQL MCP** is not configured or **`CLAWQL_OBSIDIAN_VAULT_PATH`** is unset, say so briefly and continue without blocking. -**Never store secrets:** tokens, API keys, passwords, private keys, or raw session cookies. Summarize redacted config instead. +### Cursor Agent: `call_mcp_tool` server parameter + +Your `mcp.json` key can stay **`clawql`** (that is what Settings / docs refer to). The **agent `call_mcp_tool` API** does **not** accept that bare string: Cursor registers the server under a **scoped id** derived from where the config lives: -### editor agent agent: `call_mcp_tool` `server` parameter +| Config file | Typical `call_mcp_tool` **`server`** value | +|-------------|--------------------------------------------| +| `~/.cursor/mcp.json` | **`user-clawql`** | +| `${workspaceFolder}/.cursor/mcp.json` | **`workspace-clawql`** | -The **`server`** argument is **not** the `"clawql"` key from `.editor/mcp.json`. editor agent assigns a generated **`serverIdentifier`** (see `SERVER_METADATA.json` next to the MCP descriptor under `~/.editor/projects/.../mcps/.../`). **Read `serverIdentifier` from that file** and pass it verbatim to `call_mcp_tool`—do not guess `clawql`, `user-clawql`, or `workspace-clawql`. Discovery command: +There is **no** supported `mcp.json` field to rename this to bare `clawql` for `call_mcp_tool`—the prefix is host behavior to avoid collisions (e.g. the same key in user vs project config). If both files define `clawql`, two scoped servers can exist; use the one that matches where you configured ClawQL for this workspace. -`find ~/.editor/projects -path '*mcps*clawql*' -name SERVER_METADATA.json 2>/dev/null | head -1` +**Never store secrets:** tokens, API keys, passwords, private keys, or raw session cookies. Summarize redacted config instead. --- @@ -37,6 +42,7 @@ The **`server`** argument is **not** the `"clawql"` key from `.editor/mcp.json`. | **`insights`** | Primary prose. Markdown is fine. This is where **semantic tagging** and structure live (see below). | | **`conversation`** | Longer transcript or chat summary; stored in a fenced block under **Conversation**. | | **`toolOutputs`** | Verbatim logs: command output, errors, JSON snippets, diffs—each string becomes a block; multiple strings are separated for readability. | +| **`toolOutputsFile`** | **Server-side only:** a path (absolute or relative to the ClawQL process **`cwd`**) the **MCP server** reads as UTF-8 and uses as **`toolOutputs`**. Use for **large** bodies so the model only passes a **short path** in the tool call (not the file contents). Must fall under an allowlist (**`CLAWQL_MEMORY_INGEST_FILE_ROOTS`**, or default realpath of **`cwd`**). If both **`toolOutputsFile`** and **`toolOutputs`** are set, the **file wins**. Disable reads with **`CLAWQL_MEMORY_INGEST_FILE=0`**. | | **`wikilinks`** | List of **other vault note titles** (plain names; `[[brackets]]` optional). Rendered as **`## Related`** with `- [[Note Name]]` bullets—this is the **graph** for Obsidian. | | **`sessionId`** | Optional label for the section header (threads multi-step work). | | **`append`** | Default **true**: new section appended to an existing file with the same slug. Set **false** only to replace the file body (rare). | @@ -58,9 +64,11 @@ Results include path, score, depth, reason (`keyword` | `link` | `vector`), and ### Optional `cache` (not vault) -When **`CLAWQL_ENABLE_CACHE`** is set, the server exposes **`cache`**: **ephemeral** key/value in this process, **LRU**-bounded, **no** Markdown / **`memory.db`**. Use it for session scratch state only. For durable notes and graph recall, use **`memory_ingest`** / **`memory_recall`**. Repo reference: **[`docs/cache-tool.md`](../../../docs/cache-tool.md)** (relative from this skill file in the ClawQL repo). +**`cache`** (**ClawQL Core**, always registered) is **ephemeral** key/value in this process, **LRU**-bounded, **no** Markdown / **`memory.db`**. **`memory_ingest`** / **`memory_recall`** are on by default; set **`CLAWQL_ENABLE_MEMORY=0`** to hide, and use a configured vault to persist. Repo reference: **[`docs/mcp/cache-tool.md`](../../../docs/mcp/cache-tool.md)**. -When **`CLAWQL_ENABLE_AUDIT`** is set, the server exposes **`audit`**: **ephemeral** in-process event ring buffer — **not** the vault and **not** compliance-grade alone. Use **`memory_ingest`** for durable, human-inspectable trails. Repo reference: **[`docs/enterprise-mcp-tools.md`](../../../docs/enterprise-mcp-tools.md)** ([#89](https://github.com/danielsmithdevelopment/ClawQL/issues/89)). +The server always exposes **`audit`**: **ephemeral** in-process event ring buffer — **not** the vault and **not** compliance-grade alone. Use **`memory_ingest`** for durable, human-inspectable trails. Repo reference: **[`docs/mcp/enterprise-mcp-tools.md`](../../../docs/mcp/enterprise-mcp-tools.md)** ([#89](https://github.com/danielsmithdevelopment/ClawQL/issues/89)). + +When **`CLAWQL_ENABLE_NOTIFY`** is set, the server exposes **`notify`**: Slack **`chat.postMessage`** — **not** vault storage; use for completion signals alongside **`memory_ingest`** when you also want a durable note. Repo reference: **[`docs/mcp/notify-tool.md`](../../../docs/mcp/notify-tool.md)** ([#77](https://github.com/danielsmithdevelopment/ClawQL/issues/77)). --- @@ -84,6 +92,7 @@ One paragraph: what this note captures and why it matters. ## Commands / env - `VAR=value` … +- `CLAWQL_MEMORY_INGEST_FILE_ROOTS=/abs/path/to/ClawQL` — optional comma-separated allowlist for **`toolOutputsFile`** (default: process **`cwd`** only). `CLAWQL_MEMORY_INGEST_FILE_MAX_BYTES` (default 10M). `CLAWQL_MEMORY_INGEST_FILE=0` disables path-based reads. ## APIs & references @@ -98,7 +107,7 @@ One paragraph: what this note captures and why it matters. - [ ] Next steps ``` -Put **raw** command output, stack traces, or large JSON in **`toolOutputs`**, not inside **`insights`**, unless tiny. +Put **raw** command output, stack traces, or large JSON in **`toolOutputs`** (or, when the text is too large to pass in MCP tool JSON, **`toolOutputsFile`** on the server), not inside **`insights`**, unless tiny. ### Wikilinking strategy @@ -138,8 +147,10 @@ Put **raw** command output, stack traces, or large JSON in **`toolOutputs`**, no ## Minimal API reminder ```text -memory_ingest: title (required), insights?, conversation?, toolOutputs? (string | string[]), wikilinks? (string[]), sessionId?, append? (boolean) +memory_ingest: title (required), insights?, conversation?, toolOutputs? (string | string[]), toolOutputsFile? (path on server), wikilinks? (string[]), sessionId?, append? (boolean) memory_recall: query (required), limit?, maxDepth?, minScore? ``` -For implementation details (SQLite/pgvector, index), see `docs/memory-db-hybrid-implementation.md` in the repo when relevant. +Repo details: **[`docs/mcp/mcp-tools.md`](../../../docs/mcp/mcp-tools.md)** (section **memory_ingest**). + +For implementation details (SQLite/pgvector, index), see `docs/memory/memory-db-hybrid-implementation.md` in the repo when relevant. diff --git a/personal-site/src/lib/site.ts b/personal-site/src/lib/site.ts index 853ea03..602ea2b 100644 --- a/personal-site/src/lib/site.ts +++ b/personal-site/src/lib/site.ts @@ -186,7 +186,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-supply-chain-and-admission', - date: '2026-05-11', + date: '2026-05-06', title: 'Agentic AI Security, Part 1: Supply Chain, Golden Images, and Admission Control', description: @@ -205,7 +205,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-identity-zero-trust', - date: '2026-05-10', + date: '2026-05-07', title: 'Agentic AI Security, Part 2: Identity, Least Privilege, and Zero Trust', description: @@ -224,7 +224,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-mesh-sandbox-mcp', - date: '2026-05-09', + date: '2026-05-08', title: 'Agentic AI Security, Part 3: Service Mesh, Sandboxing, and MCP Runtime Protection', description: @@ -243,7 +243,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-data-models-observability', - date: '2026-05-08', + date: '2026-05-09', title: 'Agentic AI Security, Part 4: Data Classification, Model Integrity, and Runtime Monitoring', description: @@ -262,7 +262,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-operations-and-production', - date: '2026-05-07', + date: '2026-05-10', title: 'Agentic AI Security, Part 5: Incident Response, Automation, GPU, Workstations, and Production', description: @@ -281,7 +281,7 @@ export const featuredLinkedInPosts: FeaturedLinkedInPost[] = [ }, { slug: 'agentic-ai-security-governance-and-owasp-agentic', - date: '2026-05-06', + date: '2026-05-11', title: 'Agentic AI Security, Part 6: Threat Modeling, OWASP Agentic Top 10, and Quarterly Review', description: