fastrmemory 0.3.0 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -1,14 +1,14 @@
-{
-  "name": "fastrmemory",
-  "owner": {
-    "name": "Fastrsoft"
-  },
-  "plugins": [
-    {
-      "name": "fastrmemory",
-      "source": "./",
-      "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
-      "version": "0.3.0"
-    }
-  ]
-}
+{
+  "name": "fastrmemory",
+  "owner": {
+    "name": "Fastrsoft"
+  },
+  "plugins": [
+    {
+      "name": "fastrmemory",
+      "source": "./",
+      "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
+      "version": "0.3.1"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,18 +1,18 @@
-{
-  "name": "fastrmemory",
-  "version": "0.3.0",
-  "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
-  "author": {
-    "name": "Fastrsoft"
-  },
-  "homepage": "https://github.com/atifjubaer/fastrmemory",
-  "repository": "https://github.com/atifjubaer/fastrmemory",
-  "license": "Apache-2.0",
-  "keywords": ["memory", "mcp", "agent", "sqlite", "skills"],
-  "mcpServers": {
-    "fastrmemory": {
-      "command": "npx",
-      "args": ["-y", "fastrmemory@0.3.0", "mcp"]
-    }
-  }
-}
+{
+  "name": "fastrmemory",
+  "version": "0.3.1",
+  "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
+  "author": {
+    "name": "Fastrsoft"
+  },
+  "homepage": "https://github.com/atifjubaer/fastrmemory",
+  "repository": "https://github.com/atifjubaer/fastrmemory",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "mcp", "agent", "sqlite", "skills"],
+  "mcpServers": {
+    "fastrmemory": {
+      "command": "npx",
+      "args": ["-y", "fastrmemory@0.3.1", "mcp"]
+    }
+  }
+}

package/.cursor/mcp.json

@@ -1,8 +1,10 @@
 {
   "mcpServers": {
     "fastrmemory": {
-      "command": "fastrmemory",
+      "command": "npx",
       "args": [
+        "-y",
+        "fastrmemory@0.3.1",
         "mcp"
       ]
     }

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

@@ -1,33 +1,33 @@
----
-name: fastr-compress
-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.
----
-
-# FastrMemory: Token Compression
-
-## When to use
-- A doc or context payload exceeds the budget you need it to fit.
-- The user asks to compact a long markdown file.
-
-Do not use it on source code or on files where exact wording matters (licences, legal text, changelogs).
-
-## Steps
-1. **Preview savings** without touching disk:
-   ```js
-   fastr_compress({ filePath: "docs/guide.md", dryRun: true })
-   ```
-
-2. **Compress the file** (writes `<file>.original.md` as a backup):
-   ```js
-   fastr_compress({ filePath: "docs/guide.md", dryRun: false })
-   ```
-
-3. **Or compress text in memory** (nothing written to disk; output is returned):
-   ```js
-   fastr_compress({ content: "# Title\n\nLong conversational text...", dryRun: false })
-   ```
-
-## Guarantees to verify
-- ATX headings, fenced code blocks, URLs, and markdown links are kept intact.
-- Filler phrases, duplicate list items, and extra blank lines are removed.
-- Review any warnings in the result; restore from the `.original.md` backup if meaning was lost.
+---
+name: fastr-compress
+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.
+---
+
+# FastrMemory: Token Compression
+
+## When to use
+- A doc or context payload exceeds the budget you need it to fit.
+- The user asks to compact a long markdown file.
+
+Do not use it on source code or on files where exact wording matters (licences, legal text, changelogs).
+
+## Steps
+1. **Preview savings** without touching disk:
+   ```js
+   fastr_compress({ filePath: "docs/guide.md", dryRun: true })
+   ```
+
+2. **Compress the file** (writes `<file>.original.md` as a backup):
+   ```js
+   fastr_compress({ filePath: "docs/guide.md", dryRun: false })
+   ```
+
+3. **Or compress text in memory** (nothing written to disk; output is returned):
+   ```js
+   fastr_compress({ content: "# Title\n\nLong conversational text...", dryRun: false })
+   ```
+
+## Guarantees to verify
+- ATX headings, fenced code blocks, URLs, and markdown links are kept intact.
+- Filler phrases, duplicate list items, and extra blank lines are removed.
+- Review any warnings in the result; restore from the `.original.md` backup if meaning was lost.

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

@@ -1,62 +1,62 @@
----
-name: fastr-curate
-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.
----
-
-# FastrMemory: Curate Project Memory
-
-## When to use
-- The user states a preference or guideline, or you settle an architectural decision.
-- Two recalled memories give opposing instructions.
-- A refactor or migration invalidates existing rules.
-- You are about to make many memory changes and want a restore point.
-
-## 1. Dedupe, then remember
-Always search first:
-```js
-fastr_recall({ query: "test runner convention", budgetTokens: 800 })
-```
-- Same rule exists and is right: rate it, do not store again.
-- Exists but outdated: supersede it (step 2).
-- Nothing relevant: store it.
-```js
-fastr_remember({
-  kind: "decision",
-  module: "api",
-  title: "Validate request bodies with zod at the route boundary",
-  content: "Every route parses input with a zod schema before calling services. Services assume valid input.",
-  files: ["src/api/routes.ts"],
-  symbols: ["registerRoutes"],
-  verified: false
-})
-```
-`kind` is one of `rule`, `decision`, `error_trap`, `workflow`. Leave `verified: false` (staging) until tests confirm it; use `scope: "global"` only for organisation-wide rules; `pinned: true` sparingly.
-
-## 2. Supersede instead of duplicating
-```js
-fastr_supersede({
-  oldMemoryId: "mem_jest01",
-  newTitle: "Use Vitest, not Jest",
-  newContent: "Vitest runs ESM natively; Jest config was removed.",
-  reason: "ESM migration"
-})
-```
-
-## 3. Resolve contradictions
-```js
-fastr_conflicts({ status: "open" })
-fastr_resolve({ conflictId: 4, keepId: "mem_vitest2", forgetLoser: true, reason: "Jest removed in v0.1" })
-```
-`forgetLoser: false` only weakens the loser's score; use it when both may still apply.
-
-## 4. Score usefulness
-```js
-fastr_feedback({ memoryId: "mem_vitest2", outcome: "good", note: "Prevented adding Jest config" })
-```
-
-## 5. Snapshot before bulk changes, roll back if needed
-```js
-fastr_snapshot({ tag: "pre-auth-cleanup", description: "Before consolidating auth rules" })
-fastr_rollback({ snapshotId: "snap_xxxx" })
-```
-Audit what changed with `fastr_timeline({ module: "auth", limit: 25 })`.
+---
+name: fastr-curate
+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.
+---
+
+# FastrMemory: Curate Project Memory
+
+## When to use
+- The user states a preference or guideline, or you settle an architectural decision.
+- Two recalled memories give opposing instructions.
+- A refactor or migration invalidates existing rules.
+- You are about to make many memory changes and want a restore point.
+
+## 1. Dedupe, then remember
+Always search first:
+```js
+fastr_recall({ query: "test runner convention", budgetTokens: 800 })
+```
+- Same rule exists and is right: rate it, do not store again.
+- Exists but outdated: supersede it (step 2).
+- Nothing relevant: store it.
+```js
+fastr_remember({
+  kind: "decision",
+  module: "api",
+  title: "Validate request bodies with zod at the route boundary",
+  content: "Every route parses input with a zod schema before calling services. Services assume valid input.",
+  files: ["src/api/routes.ts"],
+  symbols: ["registerRoutes"],
+  verified: false
+})
+```
+`kind` is one of `rule`, `decision`, `error_trap`, `workflow`. Leave `verified: false` (staging) until tests confirm it; use `scope: "global"` only for organisation-wide rules; `pinned: true` sparingly.
+
+## 2. Supersede instead of duplicating
+```js
+fastr_supersede({
+  oldMemoryId: "mem_jest01",
+  newTitle: "Use Vitest, not Jest",
+  newContent: "Vitest runs ESM natively; Jest config was removed.",
+  reason: "ESM migration"
+})
+```
+
+## 3. Resolve contradictions
+```js
+fastr_conflicts({ status: "open" })
+fastr_resolve({ conflictId: 4, keepId: "mem_vitest2", forgetLoser: true, reason: "Jest removed in v0.1" })
+```
+`forgetLoser: false` only weakens the loser's score; use it when both may still apply.
+
+## 4. Score usefulness
+```js
+fastr_feedback({ memoryId: "mem_vitest2", outcome: "good", note: "Prevented adding Jest config" })
+```
+
+## 5. Snapshot before bulk changes, roll back if needed
+```js
+fastr_snapshot({ tag: "pre-auth-cleanup", description: "Before consolidating auth rules" })
+fastr_rollback({ snapshotId: "snap_xxxx" })
+```
+Audit what changed with `fastr_timeline({ module: "auth", limit: 25 })`.

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

@@ -1,47 +1,47 @@
----
-name: fastr-dag
-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.
----
-
-# FastrMemory: Multi-Agent Action DAG
-
-## When to use
-- A plan has steps that depend on each other.
-- Several agents or sessions work the same backlog and must not collide.
-- You finished an action and need the next one.
-
-## 1. Create actions with dependencies
-```js
-fastr_action_create({
-  title: "Add v2 schema migration",
-  description: "Migration plus rollback; tests in tests/schema.test.ts",
-  priority: 8
-})
-fastr_action_create({
-  title: "Implement JWT auth guard",
-  description: "Guard in src/auth/guard.ts using the v2 users table",
-  priority: 6,
-  requires: ["act_schema"],
-  conflictsWith: ["act_auth_refactor"],
-  assignedTo: "claude-code"
-})
-```
-`priority` runs 1 (lowest) to 10 (highest). Use the IDs returned by earlier calls in `requires` / `conflictsWith`.
-
-## 2. See what is unblocked
-```js
-fastr_frontier({})
-```
-
-## 3. Claim the next action atomically
-```js
-fastr_next({ agentId: "claude-code" })
-```
-This marks the highest-priority unblocked action `active` for that agent.
-
-## 4. Update status as you go
-```js
-fastr_action_update({ id: "act_xxxx", status: "done", crystallizedInto: "mem_8f2a1c" })
-fastr_action_update({ id: "act_yyyy", status: "blocked" })
-```
-Statuses: `pending`, `active`, `done`, `blocked`, `cancelled`. Marking `done` unblocks dependents; set `crystallizedInto` to the memory that captured the lesson, if any.
+---
+name: fastr-dag
+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.
+---
+
+# FastrMemory: Multi-Agent Action DAG
+
+## When to use
+- A plan has steps that depend on each other.
+- Several agents or sessions work the same backlog and must not collide.
+- You finished an action and need the next one.
+
+## 1. Create actions with dependencies
+```js
+fastr_action_create({
+  title: "Add v2 schema migration",
+  description: "Migration plus rollback; tests in tests/schema.test.ts",
+  priority: 8
+})
+fastr_action_create({
+  title: "Implement JWT auth guard",
+  description: "Guard in src/auth/guard.ts using the v2 users table",
+  priority: 6,
+  requires: ["act_schema"],
+  conflictsWith: ["act_auth_refactor"],
+  assignedTo: "claude-code"
+})
+```
+`priority` runs 1 (lowest) to 10 (highest). Use the IDs returned by earlier calls in `requires` / `conflictsWith`.
+
+## 2. See what is unblocked
+```js
+fastr_frontier({})
+```
+
+## 3. Claim the next action atomically
+```js
+fastr_next({ agentId: "claude-code" })
+```
+This marks the highest-priority unblocked action `active` for that agent.
+
+## 4. Update status as you go
+```js
+fastr_action_update({ id: "act_xxxx", status: "done", crystallizedInto: "mem_8f2a1c" })
+fastr_action_update({ id: "act_yyyy", status: "blocked" })
+```
+Statuses: `pending`, `active`, `done`, `blocked`, `cancelled`. Marking `done` unblocks dependents; set `crystallizedInto` to the memory that captured the lesson, if any.

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

@@ -1,39 +1,39 @@
----
-name: fastr-doctor
-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.
----
-
-# FastrMemory: Diagnose and Heal
-
-## When to use
-- `fastr_recall` does not find a memory that `fastr_timeline` shows exists.
-- Recall or status calls are slow, or report database errors.
-- Actions stay blocked although their prerequisites are done.
-
-## Steps
-1. **Diagnose (read-only)**:
-   ```js
-   fastr_diagnose({})
-   ```
-   Checks SQLite integrity, FTS5 index consistency, orphaned file links, action DAG edges, and journal mode.
-
-2. **Preview repairs**:
-   ```js
-   fastr_heal({ dryRun: true })
-   ```
-
-3. **Apply repairs** once the preview looks right:
-   ```js
-   fastr_heal({ dryRun: false })
-   ```
-   Rebuilds the FTS5 index, prunes orphaned links, unblocks stale DAG edges, and checkpoints the WAL.
-
-4. **Confirm**:
-   ```js
-   fastr_status({})
-   ```
-
-## Rules
-- Always diagnose before healing and report what was found.
-- If issues remain that are not fixable, tell the user; do not delete `.fastr/` files by hand.
-- CLI equivalents: `fastrmemory diagnose`, `fastrmemory heal`.
+---
+name: fastr-doctor
+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.
+---
+
+# FastrMemory: Diagnose and Heal
+
+## When to use
+- `fastr_recall` does not find a memory that `fastr_timeline` shows exists.
+- Recall or status calls are slow, or report database errors.
+- Actions stay blocked although their prerequisites are done.
+
+## Steps
+1. **Diagnose (read-only)**:
+   ```js
+   fastr_diagnose({})
+   ```
+   Checks SQLite integrity, FTS5 index consistency, orphaned file links, action DAG edges, and journal mode.
+
+2. **Preview repairs**:
+   ```js
+   fastr_heal({ dryRun: true })
+   ```
+
+3. **Apply repairs** once the preview looks right:
+   ```js
+   fastr_heal({ dryRun: false })
+   ```
+   Rebuilds the FTS5 index, prunes orphaned links, unblocks stale DAG edges, and checkpoints the WAL.
+
+4. **Confirm**:
+   ```js
+   fastr_status({})
+   ```
+
+## Rules
+- Always diagnose before healing and report what was found.
+- If issues remain that are not fixable, tell the user; do not delete `.fastr/` files by hand.
+- CLI equivalents: `fastrmemory diagnose`, `fastrmemory heal`.

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

@@ -1,51 +1,51 @@
----
-name: fastr-memory
-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.
----
-
-# FastrMemory: Recall Before You Code
-
-## When to use
-- A new task or sub-task begins (feature, bug fix, refactor, review).
-- You are about to edit or create a file you have not checked this session.
-- You hit unfamiliar architecture or a convention you are unsure about.
-
-## Steps
-
-1. **Check traps on the files you will touch** (always, before the first edit):
-   ```js
-   fastr_trap_recall({ files: ["src/auth/jwt.ts", "src/auth/guard.ts"] })
-   ```
-   For each `[TRAP]` returned, state in your plan how the change avoids it.
-
-2. **Recall rules and decisions for the task**:
-   ```js
-   fastr_recall({
-     query: "JWT expiry handling in auth guard",
-     files: ["src/auth/jwt.ts"],
-     module: "auth",
-     budgetTokens: 1500
-   })
-   ```
-   Set `includeHistory: true` only when you need superseded rules (for example, to learn why something changed).
-
-   Or get one token-budgeted context block (rules + traps + ready tasks + last handoff):
-   ```js
-   fastr_assemble({
-     taskDescription: "Add refresh-token rotation to the auth guard",
-     targetFiles: ["src/auth/guard.ts"],
-     module: "auth",
-     budgetTokens: 2000
-   })
-   ```
-
-3. **Drill down only when needed**:
-   - Everything linked to one file: `fastr_file_history({ filePath: "src/auth/jwt.ts" })`
-   - Neighbouring files and memories: `fastr_graph_query({ filePath: "src/auth/jwt.ts", depth: 2 })`
-   - Verbatim stack trace or diff behind a memory: `fastr_drill({ memoryId: "mem_8f2a1c" })`
-   - Where the last session stopped: `fastr_handoff({ action: "latest" })`
-
-## Ground rules
-- If recall returns nothing, say so. Do not invent project conventions.
-- Note the IDs of memories you relied on; rate them at the end with the `fastr-session-commit` skill.
-- When a failure is diagnosed mid-task, switch to the `fastr-trap-log` skill immediately.
+---
+name: fastr-memory
+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.
+---
+
+# FastrMemory: Recall Before You Code
+
+## When to use
+- A new task or sub-task begins (feature, bug fix, refactor, review).
+- You are about to edit or create a file you have not checked this session.
+- You hit unfamiliar architecture or a convention you are unsure about.
+
+## Steps
+
+1. **Check traps on the files you will touch** (always, before the first edit):
+   ```js
+   fastr_trap_recall({ files: ["src/auth/jwt.ts", "src/auth/guard.ts"] })
+   ```
+   For each `[TRAP]` returned, state in your plan how the change avoids it.
+
+2. **Recall rules and decisions for the task**:
+   ```js
+   fastr_recall({
+     query: "JWT expiry handling in auth guard",
+     files: ["src/auth/jwt.ts"],
+     module: "auth",
+     budgetTokens: 1500
+   })
+   ```
+   Set `includeHistory: true` only when you need superseded rules (for example, to learn why something changed).
+
+   Or get one token-budgeted context block (rules + traps + ready tasks + last handoff):
+   ```js
+   fastr_assemble({
+     taskDescription: "Add refresh-token rotation to the auth guard",
+     targetFiles: ["src/auth/guard.ts"],
+     module: "auth",
+     budgetTokens: 2000
+   })
+   ```
+
+3. **Drill down only when needed**:
+   - Everything linked to one file: `fastr_file_history({ filePath: "src/auth/jwt.ts" })`
+   - Neighbouring files and memories: `fastr_graph_query({ filePath: "src/auth/jwt.ts", depth: 2 })`
+   - Verbatim stack trace or diff behind a memory: `fastr_drill({ memoryId: "mem_8f2a1c" })`
+   - Where the last session stopped: `fastr_handoff({ action: "latest" })`
+
+## Ground rules
+- If recall returns nothing, say so. Do not invent project conventions.
+- Note the IDs of memories you relied on; rate them at the end with the `fastr-session-commit` skill.
+- When a failure is diagnosed mid-task, switch to the `fastr-trap-log` skill immediately.

package/.cursor/skills/fastr-plan-estimate/SKILL.md

@@ -1,45 +1,45 @@
----
-name: fastr-plan-estimate
-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.
----
-
-# FastrMemory: Calibrated Estimates and Risk
-
-## When to use
-- You are asked for an effort or time estimate.
-- You are planning edits to files with a history of breakage.
-- A previously estimated task is complete (close the prediction).
-
-## 1. Check the base rate for this kind of work
-```js
-fastr_predict_baserate({ classTag: "migration" })
-```
-If history exists, multiply your inside-view estimate by the reported median ratio. Pick a stable `classTag` (for example `migration`, `refactor`, `bugfix`, `feature`) and reuse it.
-
-## 2. Check pre-edit risk for the target files
-```js
-fastr_risk_predict({ targetFiles: ["src/db/schema.ts", "src/db/repository.ts"], module: "db" })
-```
-High risk means: read the traps (`fastr-memory` skill), plan smaller steps, and add tests first.
-
-## 3. Record the estimate
-```js
-fastr_predict({
-  action: "create",
-  classTag: "migration",
-  claimText: "Add bi-temporal columns to the actions table",
-  estimateValue: 3,
-  estimateUnit: "hours"
-})
-```
-Note the returned prediction ID.
-
-## 4. Close it when the work is done
-```js
-fastr_predict({ action: "close", predictionId: 12, actualValue: 5 })
-```
-List open predictions with `fastr_predict({ action: "list", classTag: "migration" })`.
-
-## Rules
-- Report the calibrated number, and say what the raw estimate was.
-- Always close predictions; unclosed ones never improve future calibration.
+---
+name: fastr-plan-estimate
+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.
+---
+
+# FastrMemory: Calibrated Estimates and Risk
+
+## When to use
+- You are asked for an effort or time estimate.
+- You are planning edits to files with a history of breakage.
+- A previously estimated task is complete (close the prediction).
+
+## 1. Check the base rate for this kind of work
+```js
+fastr_predict_baserate({ classTag: "migration" })
+```
+If history exists, multiply your inside-view estimate by the reported median ratio. Pick a stable `classTag` (for example `migration`, `refactor`, `bugfix`, `feature`) and reuse it.
+
+## 2. Check pre-edit risk for the target files
+```js
+fastr_risk_predict({ targetFiles: ["src/db/schema.ts", "src/db/repository.ts"], module: "db" })
+```
+High risk means: read the traps (`fastr-memory` skill), plan smaller steps, and add tests first.
+
+## 3. Record the estimate
+```js
+fastr_predict({
+  action: "create",
+  classTag: "migration",
+  claimText: "Add bi-temporal columns to the actions table",
+  estimateValue: 3,
+  estimateUnit: "hours"
+})
+```
+Note the returned prediction ID.
+
+## 4. Close it when the work is done
+```js
+fastr_predict({ action: "close", predictionId: 12, actualValue: 5 })
+```
+List open predictions with `fastr_predict({ action: "list", classTag: "migration" })`.
+
+## Rules
+- Report the calibrated number, and say what the raw estimate was.
+- Always close predictions; unclosed ones never improve future calibration.