fastrmemory 0.3.0 → 0.3.1

package/.cursor/skills/fastr-session-commit/SKILL.md

@@ -1,49 +1,49 @@
----
-name: fastr-session-commit
-description: Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified.
----
-
-# FastrMemory: Commit the Session
-
-## When to use
-- The task is done and the test suite passes.
-- You are yielding to the user or another agent, or context is about to be compacted.
-- You are resuming work and need to know where the last session stopped.
-
-## Steps
-
-1. **Supersede rules your change made obsolete** (keeps history, redirects future recall):
-   ```js
-   fastr_supersede({
-     oldMemoryId: "mem_8f2a1c",
-     newTitle: "Use Vitest for all unit tests",
-     newContent: "The project migrated from Jest to Vitest for native ESM. Do not add Jest config.",
-     reason: "Test runner migration",
-     files: ["vitest.config.ts"]
-   })
-   ```
-
-2. **Rate each memory you actually relied on** (per ID, never the whole batch):
-   ```js
-   fastr_feedback({ memoryId: "mem_3c9d0e", outcome: "good" })
-   fastr_feedback({ memoryId: "mem_77ab12", outcome: "bad", note: "Described the old config loader" })
-   ```
-
-3. **Save the handoff and verify staging**:
-   ```js
-   fastr_handoff({
-     action: "save",
-     taskTitle: "Refresh-token rotation in auth guard",
-     summary: "Added rotation and revocation list; all auth tests pass.",
-     nextStep: "Wire revocation list cleanup into the nightly job.",
-     activeFiles: ["src/auth/guard.ts", "src/auth/jwt.ts"],
-     verifyStaging: true
-   })
-   ```
-   Only pass `verifyStaging: true` when tests pass; it promotes every staging memory from this project to verified.
-
-## Resuming a session
-```js
-fastr_handoff({ action: "latest" })
-```
-Read the summary and next step before planning, then follow the `fastr-memory` skill.
+---
+name: fastr-session-commit
+description: Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified.
+---
+
+# FastrMemory: Commit the Session
+
+## When to use
+- The task is done and the test suite passes.
+- You are yielding to the user or another agent, or context is about to be compacted.
+- You are resuming work and need to know where the last session stopped.
+
+## Steps
+
+1. **Supersede rules your change made obsolete** (keeps history, redirects future recall):
+   ```js
+   fastr_supersede({
+     oldMemoryId: "mem_8f2a1c",
+     newTitle: "Use Vitest for all unit tests",
+     newContent: "The project migrated from Jest to Vitest for native ESM. Do not add Jest config.",
+     reason: "Test runner migration",
+     files: ["vitest.config.ts"]
+   })
+   ```
+
+2. **Rate each memory you actually relied on** (per ID, never the whole batch):
+   ```js
+   fastr_feedback({ memoryId: "mem_3c9d0e", outcome: "good" })
+   fastr_feedback({ memoryId: "mem_77ab12", outcome: "bad", note: "Described the old config loader" })
+   ```
+
+3. **Save the handoff and verify staging**:
+   ```js
+   fastr_handoff({
+     action: "save",
+     taskTitle: "Refresh-token rotation in auth guard",
+     summary: "Added rotation and revocation list; all auth tests pass.",
+     nextStep: "Wire revocation list cleanup into the nightly job.",
+     activeFiles: ["src/auth/guard.ts", "src/auth/jwt.ts"],
+     verifyStaging: true
+   })
+   ```
+   Only pass `verifyStaging: true` when tests pass; it promotes every staging memory from this project to verified.
+
+## Resuming a session
+```js
+fastr_handoff({ action: "latest" })
+```
+Read the summary and next step before planning, then follow the `fastr-memory` skill.

package/.cursor/skills/fastr-setup/SKILL.md

@@ -1,45 +1,45 @@
----
-name: fastr-setup
-description: Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification.
-allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
----
-
-# FastrMemory: Wire Up Claude Code
-
-## When to use
-- `fastr_*` tools are not available in the session.
-- The user asks to set up FastrMemory for this repository.
-- Pre-edit trap warnings or session-start context stopped appearing.
-
-## 1. Project install (recommended)
-Run from the project root:
-```bash
-npx -y fastrmemory@0.3.0 hook install
-```
-This is idempotent and backs up files it changes. It writes:
-- `.mcp.json`: a project-scoped `fastrmemory` MCP server.
-- `.claude/settings.json`: hooks for `SessionStart`, `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`), `PreCompact`, and `SessionEnd`, each running the FastrMemory CLI as `... hook run <event>`.
-- `.cursor/mcp.json` and an `AGENTS.md` discipline block for other agents.
-
-Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Restart Claude Code and approve the project MCP server when prompted.
-
-## 2. Manual MCP registration (alternative)
-```bash
-claude mcp add fastrmemory -- npx -y fastrmemory@0.3.0 mcp
-```
-On native Windows use `-- cmd /c npx -y fastrmemory@0.3.0 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. This adds tools only, not hooks.
-
-## 3. Verify
-```bash
-npx -y fastrmemory@0.3.0 status
-claude mcp list
-```
-`status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:
-```js
-fastr_status({})
-```
-
-## Troubleshooting
-- Tools missing after install: run `/mcp` in Claude Code and check the server started; requires Node >= 22.16.
-- Searches miss new memories or the DB looks inconsistent: follow the `fastr-doctor` skill.
-- Do not edit `~/.claude` files by hand; prefer the commands above.
+---
+name: fastr-setup
+description: Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification.
+allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
+---
+
+# FastrMemory: Wire Up Claude Code
+
+## When to use
+- `fastr_*` tools are not available in the session.
+- The user asks to set up FastrMemory for this repository.
+- Pre-edit trap warnings or session-start context stopped appearing.
+
+## 1. Project install (recommended)
+Run from the project root:
+```bash
+npx -y fastrmemory@0.3.1 hook install
+```
+This is idempotent and backs up files it changes. It writes:
+- `.mcp.json`: a project-scoped `fastrmemory` MCP server.
+- `.claude/settings.json`: hooks for `SessionStart`, `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`), `PreCompact`, and `SessionEnd`, each running the FastrMemory CLI as `... hook run <event>`.
+- `.cursor/mcp.json` and an `AGENTS.md` discipline block for other agents.
+
+Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Restart Claude Code and approve the project MCP server when prompted.
+
+## 2. Manual MCP registration (alternative)
+```bash
+claude mcp add fastrmemory -- npx -y fastrmemory@0.3.1 mcp
+```
+On native Windows use `-- cmd /c npx -y fastrmemory@0.3.1 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. For a user-scoped registration (the default when `--scope project` is omitted), append `--project <absolute-project-path>` so the server does not use the client's launch directory; `fastr setup` writes that path automatically. This adds tools only, not hooks.
+
+## 3. Verify
+```bash
+npx -y fastrmemory@0.3.1 status
+claude mcp list
+```
+`status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:
+```js
+fastr_status({})
+```
+
+## Troubleshooting
+- Tools missing after install: run `/mcp` in Claude Code and check the server started; requires Node >= 22.16.
+- Searches miss new memories or the DB looks inconsistent: follow the `fastr-doctor` skill.
+- Do not edit `~/.claude` files by hand; prefer the commands above.

package/.cursor/skills/fastr-trap-log/SKILL.md

@@ -1,39 +1,39 @@
----
-name: fastr-trap-log
-description: Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session.
----
-
-# FastrMemory: Log Error Traps Immediately
-
-## When to use
-- A test, type check, or build failed and you now know why.
-- A runtime crash or wrong behaviour was traced to a specific cause.
-- You hit a subtle environment trap (Windows paths, SQLite locking, ESM/CJS interop, timezone, rounding).
-
-Skip it for typos or one-off mistakes that teach nothing reusable.
-
-## Steps
-
-1. **Check it is not already recorded**:
-   ```js
-   fastr_trap_recall({ files: ["src/db/schema.ts"] })
-   ```
-   If the same trap exists, do not duplicate it; rate it instead with
-   `fastr_feedback({ memoryId: "mem_xxxx", outcome: "good", note: "Trap matched this failure" })`.
-
-2. **Log the trap** (stored as a verified `error_trap` with a 2.0x recall boost):
-   ```js
-   fastr_trap_log({
-     title: "Never open two write connections to the SQLite DB",
-     content: "Symptom: SQLITE_BUSY in tests. Cause: a second DatabaseSync writer outside the shared repo. Fix: reuse the server context's db handle.",
-     files: ["src/db/schema.ts", "src/mcp/server.ts"],
-     module: "db"
-   })
-   ```
-
-## Writing a good trap
-- `title`: imperative rule, not a description of the bug ("Always X" / "Never Y").
-- `content`: symptom, root cause, and the concrete fix or workaround, in a few sentences.
-- `files`: every file where the trap applies; this is what pre-edit checks match on.
-- Never paste secrets, tokens, or private URLs. Content is scrubbed, but do not rely on it.
-- If the fix changes an existing rule, also follow the `fastr-curate` skill to supersede it.
+---
+name: fastr-trap-log
+description: Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session.
+---
+
+# FastrMemory: Log Error Traps Immediately
+
+## When to use
+- A test, type check, or build failed and you now know why.
+- A runtime crash or wrong behaviour was traced to a specific cause.
+- You hit a subtle environment trap (Windows paths, SQLite locking, ESM/CJS interop, timezone, rounding).
+
+Skip it for typos or one-off mistakes that teach nothing reusable.
+
+## Steps
+
+1. **Check it is not already recorded**:
+   ```js
+   fastr_trap_recall({ files: ["src/db/schema.ts"] })
+   ```
+   If the same trap exists, do not duplicate it; rate it instead with
+   `fastr_feedback({ memoryId: "mem_xxxx", outcome: "good", note: "Trap matched this failure" })`.
+
+2. **Log the trap** (stored as a verified `error_trap` with a 2.0x recall boost):
+   ```js
+   fastr_trap_log({
+     title: "Never open two write connections to the SQLite DB",
+     content: "Symptom: SQLITE_BUSY in tests. Cause: a second DatabaseSync writer outside the shared repo. Fix: reuse the server context's db handle.",
+     files: ["src/db/schema.ts", "src/mcp/server.ts"],
+     module: "db"
+   })
+   ```
+
+## Writing a good trap
+- `title`: imperative rule, not a description of the bug ("Always X" / "Never Y").
+- `content`: symptom, root cause, and the concrete fix or workaround, in a few sentences.
+- `files`: every file where the trap applies; this is what pre-edit checks match on.
+- Never paste secrets, tokens, or private URLs. Content is scrubbed, but do not rely on it.
+- If the fix changes an existing rule, also follow the `fastr-curate` skill to supersede it.

package/.cursor/skills/fastr-vision/SKILL.md

@@ -1,35 +1,35 @@
----
-name: fastr-vision
-description: Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them.
----
-
-# FastrMemory: Visual Memory
-
-## When to use
-- The user shares a screenshot or diagram that explains a bug, design, or architecture.
-- A test or tool produced an image worth keeping (visual regression, error dialog).
-- You are about to change UI and want earlier screenshots or design references.
-
-## 1. Tag an image
-```js
-fastr_vision_tag({
-  filePath: "screenshots/checkout-401.png",
-  description: "Checkout modal showing a red HTTP 401 banner above the pay button",
-  ocrText: "HTTP 401 Unauthorized. Access token expired.",
-  memoryId: "mem_009e4a7d",
-  taskId: "act_checkout_fix"
-})
-```
-- `description`: components, layout, colours, and what is wrong or notable.
-- `ocrText`: exact visible text (error messages, codes, labels) to make keyword search work.
-- `memoryId` / `taskId` (optional): link the governing trap or rule, and the related action.
-
-## 2. Search images
-```js
-fastr_vision_search({ query: "checkout modal 401 error", limit: 5 })
-```
-Filter to images linked to one memory with `memoryId: "mem_009e4a7d"`.
-
-## Rules
-- Describe what is in the image; do not guess at content you cannot see.
-- Do not tag images containing secrets or personal data.
+---
+name: fastr-vision
+description: Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them.
+---
+
+# FastrMemory: Visual Memory
+
+## When to use
+- The user shares a screenshot or diagram that explains a bug, design, or architecture.
+- A test or tool produced an image worth keeping (visual regression, error dialog).
+- You are about to change UI and want earlier screenshots or design references.
+
+## 1. Tag an image
+```js
+fastr_vision_tag({
+  filePath: "screenshots/checkout-401.png",
+  description: "Checkout modal showing a red HTTP 401 banner above the pay button",
+  ocrText: "HTTP 401 Unauthorized. Access token expired.",
+  memoryId: "mem_009e4a7d",
+  taskId: "act_checkout_fix"
+})
+```
+- `description`: components, layout, colours, and what is wrong or notable.
+- `ocrText`: exact visible text (error messages, codes, labels) to make keyword search work.
+- `memoryId` / `taskId` (optional): link the governing trap or rule, and the related action.
+
+## 2. Search images
+```js
+fastr_vision_search({ query: "checkout modal 401 error", limit: 5 })
+```
+Filter to images linked to one memory with `memoryId: "mem_009e4a7d"`.
+
+## Rules
+- Describe what is in the image; do not guess at content you cannot see.
+- Do not tag images containing secrets or personal data.

package/.cursor/skills/skills.json

@@ -1,65 +1,65 @@
-{
-  "$schema": "https://skills.sh/schema/v1.json",
-  "name": "fastrmemory-skills",
-  "version": "0.3.0",
-  "description": "Agent Skills that teach coding agents when to recall, log traps, curate, and commit FastrMemory.",
-  "author": "Fastrsoft",
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/atifjubaer/fastrmemory",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/atifjubaer/fastrmemory.git"
-  },
-  "skills": [
-    {
-      "name": "fastr-memory",
-      "path": "skills/fastr-memory/SKILL.md",
-      "description": "Use at the start of any coding task and before reading-to-edit, creating, or modifying project files. Checks FastrMemory for [TRAP] warnings on the target files, then recalls relevant rules and decisions so you do not repeat known mistakes or contradict project conventions."
-    },
-    {
-      "name": "fastr-trap-log",
-      "path": "skills/fastr-trap-log/SKILL.md",
-      "description": "Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session."
-    },
-    {
-      "name": "fastr-session-commit",
-      "path": "skills/fastr-session-commit/SKILL.md",
-      "description": "Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified."
-    },
-    {
-      "name": "fastr-curate",
-      "path": "skills/fastr-curate/SKILL.md",
-      "description": "Use when you learn something durable worth keeping (a new convention, an architectural decision, a user preference), when recalled memories contradict each other, or when memory needs cleanup. Dedupes before storing, records or supersedes rules, resolves conflicts, and snapshots memory before risky bulk changes."
-    },
-    {
-      "name": "fastr-setup",
-      "path": "skills/fastr-setup/SKILL.md",
-      "description": "Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification."
-    },
-    {
-      "name": "fastr-plan-estimate",
-      "path": "skills/fastr-plan-estimate/SKILL.md",
-      "description": "Use when the user asks how long or how risky a change will be, before committing to an estimate or plan for a migration, refactor, or bug fix, and again when that work finishes so the estimate can be closed with the actual result. Calibrates estimates against the project's own track record."
-    },
-    {
-      "name": "fastr-dag",
-      "path": "skills/fastr-dag/SKILL.md",
-      "description": "Use when work splits into several dependent steps, when multiple agents share one task list, or when you need to know what to work on next. Builds a task DAG with dependencies and conflicts, claims the next unblocked action, and marks progress."
-    },
-    {
-      "name": "fastr-doctor",
-      "path": "skills/fastr-doctor/SKILL.md",
-      "description": "Use when FastrMemory searches miss memories you just stored, recall is slow or erroring, the action frontier looks stuck, or the user asks to check or repair the memory database. Diagnoses first, previews repairs, then heals."
-    },
-    {
-      "name": "fastr-compress",
-      "path": "skills/fastr-compress/SKILL.md",
-      "description": "Use when a markdown file, PR description, or block of context is too long for the token budget you need to fit it into, or the user asks to shrink a doc. Compresses prose while preserving headings, code blocks, and links; always preview first."
-    },
-    {
-      "name": "fastr-vision",
-      "path": "skills/fastr-vision/SKILL.md",
-      "description": "Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them."
-    }
-  ]
-}
+{
+  "$schema": "https://skills.sh/schema/v1.json",
+  "name": "fastrmemory-skills",
+  "version": "0.3.1",
+  "description": "Agent Skills that teach coding agents when to recall, log traps, curate, and commit FastrMemory.",
+  "author": "Fastrsoft",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/atifjubaer/fastrmemory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atifjubaer/fastrmemory.git"
+  },
+  "skills": [
+    {
+      "name": "fastr-memory",
+      "path": "skills/fastr-memory/SKILL.md",
+      "description": "Use at the start of any coding task and before reading-to-edit, creating, or modifying project files. Checks FastrMemory for [TRAP] warnings on the target files, then recalls relevant rules and decisions so you do not repeat known mistakes or contradict project conventions."
+    },
+    {
+      "name": "fastr-trap-log",
+      "path": "skills/fastr-trap-log/SKILL.md",
+      "description": "Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session."
+    },
+    {
+      "name": "fastr-session-commit",
+      "path": "skills/fastr-session-commit/SKILL.md",
+      "description": "Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified."
+    },
+    {
+      "name": "fastr-curate",
+      "path": "skills/fastr-curate/SKILL.md",
+      "description": "Use when you learn something durable worth keeping (a new convention, an architectural decision, a user preference), when recalled memories contradict each other, or when memory needs cleanup. Dedupes before storing, records or supersedes rules, resolves conflicts, and snapshots memory before risky bulk changes."
+    },
+    {
+      "name": "fastr-setup",
+      "path": "skills/fastr-setup/SKILL.md",
+      "description": "Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification."
+    },
+    {
+      "name": "fastr-plan-estimate",
+      "path": "skills/fastr-plan-estimate/SKILL.md",
+      "description": "Use when the user asks how long or how risky a change will be, before committing to an estimate or plan for a migration, refactor, or bug fix, and again when that work finishes so the estimate can be closed with the actual result. Calibrates estimates against the project's own track record."
+    },
+    {
+      "name": "fastr-dag",
+      "path": "skills/fastr-dag/SKILL.md",
+      "description": "Use when work splits into several dependent steps, when multiple agents share one task list, or when you need to know what to work on next. Builds a task DAG with dependencies and conflicts, claims the next unblocked action, and marks progress."
+    },
+    {
+      "name": "fastr-doctor",
+      "path": "skills/fastr-doctor/SKILL.md",
+      "description": "Use when FastrMemory searches miss memories you just stored, recall is slow or erroring, the action frontier looks stuck, or the user asks to check or repair the memory database. Diagnoses first, previews repairs, then heals."
+    },
+    {
+      "name": "fastr-compress",
+      "path": "skills/fastr-compress/SKILL.md",
+      "description": "Use when a markdown file, PR description, or block of context is too long for the token budget you need to fit it into, or the user asks to shrink a doc. Compresses prose while preserving headings, code blocks, and links; always preview first."
+    },
+    {
+      "name": "fastr-vision",
+      "path": "skills/fastr-vision/SKILL.md",
+      "description": "Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them."
+    }
+  ]
+}