@radix-ai/ai-memory 0.1.0

package/plugins/ai-memory/agents/governance-critic/AGENT.md

@@ -0,0 +1,57 @@
+---
+name: governance-critic
+description: Red-teams the governance harness. Finds [P0] rules the current harness.json would fail to catch. Run after adding new P0 entries or when a constraint violation slipped through.
+type: agent
+status: active
+---
+
+# Governance Critic
+
+Inherits base methodology from `.ai/agents/_base-auditor.md`.
+
+## Role
+
+Find weaknesses in the current rule set. The harness is only as good as the rules it contains and the test cases that cover them. This agent finds the gaps.
+
+## When to invoke
+
+- After adding a new [P0] entry with `constraint_pattern`
+- After a constraint violation slipped through the governance gate undetected
+- When `ai-memory eval` shows low rule coverage
+- Before a major release
+
+## Methodology
+
+### 1. Load current rules
+Read `.ai/temp/harness.json`. Read the corresponding [P0] entries from `decisions.md` and `debugging.md`.
+
+### 2. Test each rule
+For each rule in harness.json:
+- Construct a code snippet that clearly violates the rule
+- Construct a code snippet that clearly does not violate the rule (but is similar enough to be a false-positive risk)
+- Note whether existing `rule-tests/tests.json` already covers this
+
+### 3. Find false negative risks
+- Are there alternative ways to express the same violation that the pattern wouldn't catch? (e.g., dynamic imports, aliased functions, indirect calls)
+- If yes → suggest a refined pattern or additional rule
+
+### 4. Find false positive risks
+- Is the pattern too broad? Would it flag valid code?
+- If yes → suggest narrowing the pattern with a `where` clause or stricter path filter
+
+### 5. Find uncovered P0 entries
+- Are there [P0] entries with no `constraint_pattern`?
+- For each: assess whether the rule can realistically be expressed as an AST or regex pattern
+- If yes → propose a `constraint_pattern` block to add to the entry
+
+## Report Format
+
+For each finding:
+```
+Rule: <rule_id>
+Issue: <false negative / false positive / uncovered>
+Example: <code snippet demonstrating the issue>
+Proposed fix: <refined pattern or new constraint_pattern>
+```
+
+End with: total rules reviewed, issues found, suggested additions.

package/plugins/ai-memory/agents/memory-auditor/AGENT.md

@@ -0,0 +1,54 @@
+---
+name: memory-auditor
+description: Audits .ai/ memory for gaps, stale entries, P0 entries missing constraint_pattern, and broken links. Run periodically or before a major release.
+type: agent
+status: active
+---
+
+# Memory Auditor
+
+Inherits base methodology from `.ai/agents/_base-auditor.md`.
+
+## Role
+
+Review the state of `.ai/memory/` and surface issues that reduce the quality of AI assistance over time.
+
+## When to invoke
+
+- Before a major release or milestone
+- When the AI repeatedly makes the same mistakes
+- When `ai-memory eval` shows declining metrics
+- Monthly for active projects
+
+## Methodology
+
+### 1. Load context
+Read `memory-index.md`, then read `decisions.md`, `patterns.md`, and `debugging.md` in full.
+
+### 2. Check for gaps
+For each [P0] entry:
+- Does it have a `constraint_pattern`? If not → flag as "unenforced P0"
+- Is the rule clear enough to be expressed as code? If yes → suggest a `constraint_pattern`
+
+### 3. Check for stale entries
+- Entries marked `[DEPRECATED]` older than 60 days → flag for archiving
+- P2 entries not referenced in thread-archive or open-items in 90+ days → flag for review
+- Decisions with `**Superseded by:**` where the referenced entry doesn't exist → flag as broken link
+
+### 4. Check for coverage gaps
+- Topics that appear frequently in thread-archive but have no corresponding decisions or patterns entry → flag as undocumented knowledge
+- Bugs in debugging.md that have a [P0] tag but no corresponding decision → suggest creating a decision entry
+
+### 5. Check index
+- Does `memory-index.md` reflect current entries? If it's out of date → flag for regeneration
+
+## Report Format
+
+Group findings by severity:
+
+- **CRITICAL:** Broken links, corrupted frontmatter
+- **HIGH:** Unenforced [P0] entries (no constraint_pattern)
+- **MEDIUM:** Stale deprecated entries, coverage gaps
+- **LOW:** P2 entries pending review, index freshness
+
+End with: "Recommended next action: [most impactful single thing to fix]"

package/plugins/ai-memory/rules/context7-tool-reference.md

@@ -0,0 +1,16 @@
+---
+name: context7-tool-reference
+description: Use Context7 when fetching or updating AI tool documentation in docs/reference
+globs: docs/reference/**/*
+alwaysApply: false
+---
+
+## Context7 for tool reference
+
+When adding, updating, or verifying entries in `docs/reference/tools/`:
+
+1. **Always use Context7** — Call `resolve-library-id` then `query-docs` (MCP) or `ctx7 library` + `ctx7 docs` (CLI). Do not rely on cached or outdated web search.
+2. **Add library ID** — Record the resolved Context7 library ID in the tool file's Context7 section.
+3. **Fetch 2026/2025 docs** — Use Context7 to ensure latest documentation; fall back to 2025 if nothing newer.
+
+See `docs/reference/CONTEXT7_RULE.md` for full details and library ID reference.

package/plugins/ai-memory/rules/load-memory.md

@@ -0,0 +1,22 @@
+---
+name: load-memory
+description: Load project memory at session start. Required for ai-memory to work in any IDE.
+alwaysApply: true
+---
+
+This project has persistent AI memory in `.ai/`.
+
+- **IDENTITY.md** — project constraints and behavioral rules
+- **PROJECT_STATUS.md** — current focus, open questions, what to try next (writable)
+- **memory/** — decisions, patterns, debugging history
+
+Use `search_memory` (MCP) to find relevant context before starting a task.
+Use `commit_memory` to write new entries — never edit memory files directly.
+If MCP is not connected, read `.ai/memory/memory-index.md` for a summary and write to `.ai/memory/` files directly.
+
+`.ai/` is the canonical memory for this project. Save all project learnings here, not in your tool's built-in memory (e.g. ~/.claude/, Cursor memory, etc.). Tool-native memory is for user preferences only.
+
+IDENTITY.md is immutable by default — do not write to it unless `writable: true` is set in its frontmatter.
+Immutable paths: toolbox/, acp/, rules/.
+
+At session end: run `/mem-compound` to persist learnings. In ephemeral environments (worktrees, cloud agents), also call `sync_memory`.

package/plugins/ai-memory/rules/parallel-safe-planning.md

@@ -0,0 +1,19 @@
+---
+name: parallel-safe-planning
+description: When creating plans for sub-agents or parallel execution, design tasks that do not create code conflicts.
+alwaysApply: true
+---
+
+When creating a plan or task list that will be executed by multiple agents or sub-agents (worktrees, background agents, parallel sessions):
+
+1. **Each task must touch a distinct set of files.** Two tasks should never modify the same file. If they must, one should depend on the other (sequential, not parallel).
+
+2. **Scope tasks by module, not by layer.** "Add login feature" is parallelizable. "Update all controllers" is not — it touches files other tasks may also touch.
+
+3. **Mark dependencies explicitly.** If task B requires task A's output, say so: `depends_on: task-a`. Agents will claim independent tasks first.
+
+4. **Shared files go last.** Tasks that modify shared files (config, routes, index exports) should be a final sequential step, not parallelized.
+
+5. **Test tasks are independent.** Writing tests for module X does not conflict with writing tests for module Y. These can always run in parallel.
+
+When using `claim_task`, agents will pick unclaimed tasks. If the plan follows these rules, two agents claiming different tasks will never produce merge conflicts.

package/plugins/ai-memory/skills/mem-auto-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: mem-auto-review
+description: Automated PR review using ai-memory governance rules. Designed for Cursor automations, Bugbot, and CI pipelines. No user interaction required.
+---
+
+# mem-auto-review — Automated PR Review
+
+## When to use
+
+- Triggered by PR creation (Bugbot, Cursor automation, GitHub webhook)
+- CI pipeline step
+- Any automated code review context
+
+This skill requires NO user interaction. It runs autonomously and produces a structured report.
+
+## Instructions
+
+### 1. Get the diff
+Run `git diff origin/main...HEAD` to get all changes in the PR.
+
+### 2. Search memory for context
+Call `search_memory` with keywords from the changed files. Check for:
+- Relevant decisions that may affect the changes
+- Known patterns the PR should follow
+- Previous bugs in the same area
+
+### 3. Validate governance
+Call `generate_harness` to refresh rules, then `validate_context` with the diff.
+
+### 4. Produce review
+Generate a structured review:
+
+```
+## ai-memory Review
+
+### Governance
+- [P0 violations / all clear]
+
+### Memory Context
+- [Relevant decisions from memory]
+- [Patterns that apply]
+
+### Suggestions
+- [Improvements based on project patterns]
+```
+
+### 5. Record result
+Call `publish_result` with summary and outcome (`success` if no P0 violations, `failure` if blocked).
+
+### 6. Sync
+Call `sync_memory` to persist any new learnings.

package/plugins/ai-memory/skills/mem-compound/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: mem-compound
+description: Captures session learnings into persistent memory. Use after a non-obvious bug fix, a pattern discovery, a corrected approach, or at the end of any meaningful session.
+---
+
+# mem-compound — Full Compound Loop
+
+## When to run
+
+- A bug had a non-obvious root cause
+- A reusable pattern emerged
+- An approach was corrected mid-session
+- The session produced architectural decisions
+- End of any session worth preserving
+
+Skip: purely mechanical tasks with no new learning.
+
+## Steps
+
+### 0. Pre-compact dump
+If a pre-compact dump exists in `.ai/temp/`, process it first before scanning the live session.
+
+### 1. Scan
+Review the session: conversation, code changes, errors encountered. Identify:
+- Bugs fixed with non-obvious causes → `debugging.md`
+- Reusable patterns discovered → `patterns.md`
+- Architectural or process decisions made → `decisions.md`
+- Incremental improvements worth noting → `improvements.md`
+
+### 2. Conflict check, then capture
+Before writing each entry: search existing entries for contradictions.
+
+To search: call `search_memory` with the topic of the new entry.
+
+If a contradiction is found with an existing entry:
+- Mark the old entry `[DEPRECATED]` and add `**Superseded by:** [new entry title]`
+- Write the new entry normally
+- Never delete old entries — the history of why things changed is valuable
+
+Write each entry with:
+- Priority tag: `[P0]` (critical, never violate), `[P1]` (important), `[P2]` (advisory)
+- Context, decision/pattern/fix, rationale, tradeoffs
+- Optional: `**Links to:**`, `**Supersedes:**`
+
+For `[P0]` entries, add a `constraint_pattern` in frontmatter if the rule can be expressed as a code check (see `.ai/temp/harness.json` format).
+
+### 3. Update PROJECT_STATUS.md
+PROJECT_STATUS.md is writable by default. Update it with what you learned:
+- Move completed focus items to "What's Working"
+- Add new open questions discovered during the session
+- Update "What to Try Next" based on results
+- This is the RALPH loop: each iteration evolves the plan
+
+### 4. Archive and open items
+- Call `publish_result` with a summary, outcome, and learnings
+- Update `sessions/open-items.md`: close resolved items, add new ones
+
+### 5. Regenerate index
+Call `commit_memory` with type `index` to regenerate `memory-index.md`. The index is always auto-generated — never edit it manually.
+
+### 6. Governance gate (Full tier only)
+If `.ai/temp/harness.json` exists:
+1. Call `generate_harness` to refresh rules from current [P0] entries
+2. Call `validate_context` with the current git diff
+3. Call `validate_schema` on each new memory entry
+
+If any check fails: resolve the violation before proceeding. The gate does not warn — it blocks.
+
+### 7. Sync (ephemeral environments)
+If running in a worktree, cloud agent, or sandbox: call `sync_memory` to git commit all `.ai/` changes. Without this, your work will be lost when the environment is cleaned up.
+
+### 8. Report & memory hygiene
+
+Summarize the session in a structured report:
+
+**Session summary:**
+- Entries written: list each (type, priority, title)
+- Items: N opened, N closed
+- Gate: passed / N violations resolved
+
+**Memory hygiene check:**
+Call `prune_memory` with `dry_run: true`. Then report:
+
+- **Clean** (no deprecated entries): "Memory is clean — no stale entries found."
+- **Stale entries found**: List them clearly:
+  ```
+  Found N deprecated entries:
+    1. [topic-file.md] "Entry title" — deprecated on YYYY-MM-DD
+    2. ...
+
+  To clean up, say: "prune these deprecated entries"
+  Or ignore — they're already excluded from search results.
+  ```
+
+Keep the report concise. The user should be able to act on it immediately or move on.
+
+---
+
+## Automation mode
+
+When running as a Cursor automation, Bugbot task, or CI step (no user interaction):
+- Skip any steps that require user confirmation
+- Use `search_memory` + `git diff` as input instead of conversation scanning
+- Always call `sync_memory` at the end (automations are ephemeral)
+- Output a structured report (markdown) rather than conversational summary

package/plugins/ai-memory/skills/mem-init/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: mem-init
+description: Scaffolds the .ai/ directory in the current project. Use once per project to set up persistent memory. Runs npx ai-memory init with chosen options.
+---
+
+# mem-init — Project Setup
+
+## When to use
+
+First time setting up ai-memory in a project. Run once.
+
+## Steps
+
+### 1. Confirm working directory
+Verify the current directory is the project root (where `.git/` lives).
+
+### 2. Choose tier
+
+Ask which tier to initialize:
+
+- **Default** — full memory structure + MCP server. Recommended for most projects.
+  ```
+  npx @radix-ai/ai-memory init
+  ```
+
+- **Full** — Default plus governance enforcement (harness), evals, and ACP agent card.
+  ```
+  npx @radix-ai/ai-memory init --full
+  ```
+
+### 3. Run init
+Execute the chosen command. The CLI scaffolds `.ai/` from canonical templates, adds `AGENTS.md` stub at project root, and configures tool stubs for the current IDE.
+
+### 4. Customize IDENTITY.md
+After scaffolding, open `.ai/IDENTITY.md` and fill in:
+- What this project is (one paragraph)
+- Hard constraints (what the AI must never do in this codebase)
+- Tech stack overview
+
+### 5. Customize PROJECT_STATUS.md
+Open `.ai/PROJECT_STATUS.md` and fill in:
+- Current Focus (what's actively being built)
+- Open Questions (what's not decided yet)
+
+Leave `What's Working` and `What to Try Next` blank for now — these fill in naturally over time.
+
+### 6. Confirm
+Run `npx @radix-ai/ai-memory validate` to confirm all files have valid frontmatter.

package/plugins/ai-memory/skills/mem-session-close/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mem-session-close
+description: Lite session close. Archives the session and updates open items without a full compound run. Use when ending a session that produced no new decisions or patterns worth capturing.
+---
+
+# mem-session-close — Lite Path
+
+## When to use
+
+- Session was exploratory or mechanical (no new decisions, patterns, or bugs)
+- Short session not worth a full compound run
+- Want to close cleanly without the full loop
+
+For sessions with real learning, use `/mem-compound` instead.
+
+## Steps
+
+### 1. Pre-compact dump
+If a pre-compact dump exists in `.ai/temp/`, process it first.
+
+### 2. Archive
+Add a one-line summary to `sessions/archive/thread-archive.md`:
+```
+[date] Brief description of what was done. No major decisions.
+```
+
+### 3. Open items
+Review `sessions/open-items.md`:
+- Close any items resolved during this session
+- Add any newly discovered items
+
+### 4. Sync (ephemeral environments)
+If running in a worktree, cloud agent, or sandbox: call `sync_memory` to git commit all `.ai/` changes.
+
+### 5. Report
+One line: "Session closed. [N] items updated."
+
+No index regeneration. No governance gate. No topic file writes.

package/plugins/ai-memory/skills/mem-validate/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mem-validate
+description: Manually validates proposed code changes or memory entries against project rules. Use before a risky change or when the governance gate needs to be run outside of compound.
+---
+
+# mem-validate — Manual Validation
+
+## When to use
+
+- Before a risky architectural change
+- When a compound run was skipped but governance is needed
+- To check a proposed memory entry before writing it
+- To verify the current harness is up to date
+
+## Steps
+
+### 1. Determine what to validate
+
+Choose one or both:
+- **Code change**: validate a git diff against [P0] rules
+- **Memory entry**: validate a proposed entry against the canonical schema
+
+### 2. Validate code change (if applicable)
+
+Collect the git diff:
+```
+git diff HEAD
+```
+
+Call `validate_context` with the diff. The tool returns either:
+- A list of violated [P0] rules (with which decision triggered each)
+- "No violations found"
+
+If violations are found: resolve them before proceeding. Each violation message names the specific [P0] entry that was triggered.
+
+### 3. Validate memory entry (if applicable)
+
+Call `validate_schema` with the proposed entry. The tool checks:
+- Required frontmatter fields present (`id`, `type`, `status`)
+- Field values are valid enum values
+- `constraint_pattern` is well-formed (if present)
+
+### 4. Check harness freshness (Full tier)
+
+If `.ai/temp/harness.json` exists, verify it reflects current [P0] entries:
+```
+npx @radix-ai/ai-memory validate
+```
+
+If stale: call `generate_harness` to refresh.
+
+### 5. Report
+
+List: what passed, what failed, what was refreshed.

package/templates/.ai/IDENTITY.md

@@ -0,0 +1,23 @@
+# IDENTITY.md
+
+You are a senior developer focused on long-term strategy and production readiness.
+
+## Mindset
+
+- Think about gaps and edge cases before writing code
+- Propose solutions that are production-grade, not prototypes
+- When diagnosing an issue, consider the full call chain — not just the immediate symptom
+
+## Constraints (NEVER without explicit approval)
+
+- Never commit secrets, API keys, or .env files
+- Never delete user data without explicit request
+- Never deploy to production without explicit request
+- Never write full protocols to tool directories — canonical content goes in `.ai/`, stubs in tool dirs
+
+## Before Starting Any Task
+
+1. Read `.ai/memory/memory-index.md`
+2. Search `.ai/memory/` for bugs, patterns, decisions relevant to the task
+3. Search `.ai/skills/` for applicable domain patterns
+4. Fetch `.ai/reference/PROJECT.md` only when task requires architecture, data models, or integrations

package/templates/.ai/agents/_base-auditor.md

@@ -0,0 +1,28 @@
+# Base Auditor Protocol
+
+**Shared by all auditor agents.** Defines Core Principles, Initial Steps, Report Format, Closing Steps.
+
+## Core Principles
+
+- Verify before asserting
+- Cite evidence (file:line, logs)
+- Prioritize by impact (CRITICAL > HIGH > MEDIUM > LOW)
+
+## Initial Steps
+
+1. Read scope and methodology from the specific auditor file
+2. Gather context (relevant files, configs, rules)
+3. Execute checks per methodology
+
+## Report Format
+
+- **CRITICAL:** {definition}
+- **HIGH:** {definition}
+- **MEDIUM:** {definition}
+- **LOW:** {definition}
+
+## Closing Steps
+
+- Summarize findings
+- Recommend remediation order
+- Flag any blockers

package/templates/.ai/agents/_template.md

@@ -0,0 +1,23 @@
+# {Agent Name}
+
+You are a {role description}. Your goal is {mission statement}.
+
+> **Auditor agents:** Follow the shared auditor protocol in `_base-auditor.md`.
+
+## Role-Specific Reading
+
+- {What this agent should read before starting.}
+
+## Methodology
+
+### 1. {First Area}
+
+{What to check, how to check it.}
+
+### 2. {Second Area}
+
+{...}
+
+## Output
+
+Save findings to the appropriate location. Categorize by severity.

package/templates/.ai/memory/debugging.md

@@ -0,0 +1,14 @@
+# Debugging — Non-obvious Bugs
+
+**Format:** Tag each entry with `[P0]`, `[P1]`, or `[P2]`. Include root cause and fix.
+
+---
+
+<!-- Add entries below. Example:
+
+## [P0] Vitest 4 Incompatibility
+
+**Symptom:** "No test suite found in file" after upgrading Vitest.
+**Root cause:** Vitest 4.x has a known bug.
+**Fix:** Pin to Vitest 3.2.4.
+-->

package/templates/.ai/memory/decisions.md

@@ -0,0 +1,8 @@
+# Decisions — Architectural Decisions with Rationale
+
+**Format:** Tag each entry with `[P0]`, `[P1]`, or `[P2]`. Include context, decision, rationale, tradeoffs.
+Optional: `**Supersedes:**`, `**Superseded by:**`, `**Links to:**` for graph linkage.
+
+---
+
+<!-- Add entries below. -->

package/templates/.ai/memory/improvements.md

@@ -0,0 +1,7 @@
+# Improvements — Proposed Improvements (Awaiting Decision)
+
+**Format:** Human or agent-proposed improvements. Await human decision before implementing.
+
+---
+
+<!-- Add entries below. -->

package/templates/.ai/memory/memory-index.md

@@ -0,0 +1,9 @@
+# Memory Index — Priority-Ranked Index
+
+**Auto-generated.** Parses `[P0]`, `[P1]`, `[P2]` from debugging.md, decisions.md, patterns.md.
+
+Run the index generator (e.g. `node scripts/write-memory-index.js` or `npx ai-os index`) to regenerate.
+
+---
+
+<!-- Placeholder until index generator runs. -->

package/templates/.ai/memory/patterns.md

@@ -0,0 +1,8 @@
+# Patterns — Reusable Patterns Confirmed Across Codebase
+
+**Format:** Tag each entry with `[P0]`, `[P1]`, or `[P2]`. Include pattern and anti-pattern.
+Optional: `**Links to:**` for graph linkage.
+
+---
+
+<!-- Add entries below. -->

package/templates/.ai/reference/PROJECT.md

@@ -0,0 +1,5 @@
+# PROJECT.md
+
+**Placeholder.** Replace with your project's architecture, data models, integrations, and critical warnings.
+
+Load this file only when the task requires full project context. Prefer `memory-index.md` and topic tails for session start.

package/templates/.ai/reference/capability-specs.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "capabilities": {
+    "browser": {
+      "description": "Browser automation (screenshots, navigate, interact)",
+      "environments": {
+        "cursor": { "native": true },
+        "claude-code": {
+          "mcp": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@anthropic-ai/cursor-ide-browser"]
+          }
+        },
+        "windsurf": { "mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic-ai/cursor-ide-browser"] } },
+        "cline": { "mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic-ai/cursor-ide-browser"] } }
+      }
+    },
+    "screen_capture": {
+      "description": "Desktop/app window screenshot and vision analysis",
+      "platforms": {
+        "darwin": {
+          "bins": ["peekaboo"],
+          "install": [{ "kind": "brew", "formula": "peekaboo" }]
+        },
+        "win32": { "manual": "Use built-in screenshot tools; save to .ai/temp/" },
+        "linux": { "manual": "Use gnome-screenshot or similar; save to .ai/temp/" }
+      }
+    }
+  }
+}