musememory 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musememory",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Autonomous, self-organizing cognitive memory system for AI agents and agency networks",
   "main": "dist/index.js",
   "type": "module",
@@ -10,6 +10,9 @@
   },
   "files": [
     "dist",
+    "skills",
+    ".agents",
+    "schema.json",
     "README.md",
     "LICENSE",
     "package.json"

package/schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "memory-entry",
+  "title": "MemoryEntry",
+  "type": "object",
+  "required": ["id", "title", "content", "project", "status", "created_at", "updated_at", "source", "tags"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^m_[0-9]+_[a-z0-9_-]+$" },
+    "title": { "type": "string", "maxLength": 120 },
+    "content": { "type": "string", "minLength": 1 },
+    "project": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "enum": ["candidate", "active", "confirmed", "superseded", "stale", "disputed", "rejected"] },
+    "type": { "type": "string", "enum": ["session", "decision", "fix", "failure", "architecture", "operation", "constraint", "preference", "discovery"] },
+    "salience": { "type": "number", "minimum": 0, "maximum": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "valid_from": { "type": "string", "format": "date-time" },
+    "valid_to": { "type": "string", "format": "date-time" },
+    "due_at": { "type": "string", "format": "date-time" },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "reinforcement": { "type": "integer" },
+    "source": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 8 },
+    "supersedes": { "type": ["string", "array", "null"], "items": { "type": "string" } },
+    "superseded_by": { "type": ["string", "array", "null"], "items": { "type": "string" } },
+    "disputed_by": { "type": "array", "items": { "type": "string" } },
+    "verification": {
+      "type": "object",
+      "required": ["level"],
+      "properties": {
+        "level": { "type": "string", "enum": ["unverified", "observed", "reproducible", "user-confirmed", "authoritative", "independently-verified"] },
+        "method": { "type": "string" },
+        "verified_by": { "type": "string" },
+        "verified_at": { "type": "string", "format": "date-time" },
+        "test_command": { "type": "string" },
+        "test_result": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "last_confirmed_at": { "type": ["string", "null"], "format": "date-time" },
+    "related_memory_ids": { "type": "array", "items": { "type": "string" } },
+    "session_id": { "type": "string" },
+    "test_command": { "type": "string" },
+    "graph": {
+      "type": "object",
+      "required": ["provider"],
+      "properties": {
+        "provider": { "type": "string" },
+        "graph_revision": { "type": "string" },
+        "node_ids": { "type": "array", "items": { "type": "string" } },
+        "symbol_names": { "type": "array", "items": { "type": "string" } },
+        "affected_paths": { "type": "array", "items": { "type": "string" } },
+        "impact_query": { "type": "string" },
+        "graph_verified_at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/skills/muse-brief/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: muse-brief
+description: Proactive daily briefing and knowledge hygiene governor. Scans decaying knowledge, audits policy staleness, tracks overdue due_at deadlines, and surfaces unresolved open loops with zero resident daemons.
+---
+
+# ⏰ Muse Brief (`muse-brief`)
+
+> **When to use**: Execute at the start of a workday, during daily standup/planning, or when performing knowledge hygiene and backlog triage.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Generate Actionable Daily Briefing
+Run `memory briefing` (or execute via `memory routine run daily-briefing`):
+
+```bash
+memory briefing --limit 10
+```
+
+The briefing renders a clean Markdown summary containing:
+1. **Fresh Insights**: Recently confirmed architectural decisions and bug fixes.
+2. **Upcoming & Overdue Items**: Entries with `due_at` timestamps requiring attention.
+3. **Active Constraints**: Current rules in `.memory/CURRENT.md`.
+4. **Open Loops**: Extracted tasks and unresolved commitments from recent agent sessions.
+
+### Step 2: Run Staleness & Attention Audits
+Run `memory nudge` to inspect decaying knowledge:
+- **Policy Decay Check**: Flags fixes older than 90 days or operational rules older than 180 days.
+- **Action**: Prompt the user or agent to re-verify, mark stale (`memory mark-stale <id>`), or supersede with updated patterns.
+
+### Step 3: Run Routine Automation (Zero Daemon)
+Declare routine workflows in `.memory/routines.yaml`:
+
+```yaml
+routines:
+  - name: daily-hygiene
+    schedule: "0 9 * * 1-5"
+    commands:
+      - "memory nudge"
+      - "memory briefing"
+      - "memory wiki compile"
+```
+
+Install the crontab line via `memory routine install daily-hygiene` to run via system cron without any persistent background Node daemon.
+
+---
+
+## 🛡️ Invariant Rules for Agents
+
+- **Deterministic & Zero-Daemon**: Never launch a long-running background daemon process; execute on-demand or via cron.
+- **Actionable Output**: Highlight only actionable staleness warnings and open loops rather than dumping entire databases.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Generate daily briefing
+memory briefing
+
+# Surface overdue items and decaying knowledge
+memory nudge
+
+# Execute declared routine
+memory routine run daily-hygiene
+```

package/skills/muse-capture/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: muse-capture
+description: Autonomous post-fix and architectural decision distillation. Captures atomic, verified knowledge units with inline Vibeguard secret defense and supersedes outdated patterns.
+---
+
+# 🧠 Muse Capture (`muse-capture`)
+
+> **When to use**: Execute immediately after fixing a non-trivial bug, establishing an architectural pattern, learning an operational rule, or making a system decision.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Verify Evidence Before Capturing
+Ensure the fix or decision has been verified with real build outputs, test runs, or command logs:
+- **Evidence Directive**: Do not propose speculative or unverified fixes.
+- **Verification Level**: Tag with `observed`, `reproducible`, `user-confirmed`, or `independently-verified`.
+
+### Step 2: Propose Atomic Memory Unit
+Call the `memory_capture` MCP tool:
+
+```json
+{
+  "title": "Fix SQLite Connection Pool Exhaustion under Bun Microtasks",
+  "content": "SQLite WAL mode with busy_timeout=5000ms prevents disk lock errors during concurrent microtask flushes. Use PRAGMA busy_timeout = 5000 in openDatabase.",
+  "project": "my-project",
+  "type": "fix",
+  "tags": ["sqlite", "bun", "concurrency"],
+  "salience": 0.9,
+  "verification": {
+    "level": "independently-verified",
+    "test_command": "bun test test/sqlite_concurrency.test.ts"
+  }
+}
+```
+
+### Step 3: Handle Knowledge Supersession (When Deprecating Old Knowledge)
+If the new fix or architecture replaces an outdated pattern:
+1. Identify the existing memory ID (e.g. `m_1700000001000_old_pool`).
+2. Call `memory_supersede` to atomically update bidirectional links:
+
+```json
+{
+  "old_id": "m_1700000001000_old_pool",
+  "new_id": "m_1700000002000_new_pool"
+}
+```
+
+---
+
+## 🛡️ Vibeguard Zero-Leakage Protocol
+
+- **Automatic Interception**: `memory_capture` automatically scans all proposed fields (title, content, tags, verification commands).
+- **Hard Rejection**: Any presence of AI API keys (`sk-*`), GitHub tokens (`ghp_*`), AWS keys (`AKIA*`), private keys, or passwords will immediately throw an error.
+- **Sanitization Directive**: Always redact secrets to `[REDACTED_SECRET]` before proposing.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Propose a new candidate memory
+memory capture "Fix details" --title "Title" --project my-project --type fix
+
+# Confirm a candidate memory
+memory confirm <id>
+
+# Supersede an old memory with a confirmed replacement
+memory supersede <old_id> --with <new_id>
+```

package/skills/muse-current/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: muse-current
+description: Active working constraints and interruption-proof session handoff manager. Synchronizes hard invariants, open loops, and in-flight checkpoints directly into CURRENT.md.
+---
+
+# 📐 Muse Current (`muse-current`)
+
+> **When to use**: Execute when the user establishes a hard project invariant, when starting a multi-step task, or before context compaction/task switching to record in-flight handoffs.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Record Hard Constraints
+When a non-negotiable rule or invariant is declared:
+Call `memory_current` or `memory_capture(type="constraint")`:
+
+```json
+{
+  "action": "append",
+  "text": "- Invariant: Never allow cross-origin POST mutations without Origin header check (CSRF defense)."
+}
+```
+
+This immediately updates `.memory/CURRENT.md` and dual-persists a constraint memory in SQLite.
+
+### Step 2: Record Interruption-Proof Session Handoffs
+When completing a subtask, hitting context limits, or preparing for the next agent:
+Append a structured handoff block to `CURRENT.md`:
+
+```markdown
+## Active Handoff & Session Checkpoint
+- **Goal**: Migrate SQLite WAL connection pool to asynchronous microtask flushes.
+- **Completed**:
+  - Implemented async query worker in `src/sqlite/worker.ts`.
+  - Added unit test suite `test/sqlite_worker.test.ts`.
+- **In-Flight / Next Steps**:
+  - Wire worker into `src/store.ts` save transaction.
+  - Run full suite: `bun test`.
+```
+
+### Step 3: Clear Resolved Invariants
+When a temporary constraint or migration phase is complete, update `CURRENT.md` to prune obsolete rules so future context windows stay lightweight.
+
+---
+
+## 🛡️ Invariant Rules for Agents
+
+- **High Locality**: `CURRENT.md` must contain only active, high-priority invariants and current handoffs—not historical archives.
+- **Zero Hallucination**: Do not contradict constraints recorded in `CURRENT.md`.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Read active working constraints
+memory current get
+
+# Append a new active constraint
+memory current set "- Hard constraint description" --project my-project
+```

package/skills/muse-graph/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: muse-graph
+description: AST code-aware symbol graph investigation and indexing. Integrates CodeGraph and Graphify to map codebase identifiers, auto-tag memories, and rank symbol-matching decisions with graph overlap bonuses.
+---
+
+# 🌐 Muse Graph (`muse-graph`)
+
+> **When to use**: Execute during deep codebase investigation, refactoring critical classes/modules, or diagnosing complex bugs where symbol-level architectural context is required.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Check & Index AST Symbol Graph
+Verify provider status or build the cached AST symbol map:
+- Call `graph_status` MCP tool to check provider availability (`.codegraph` or `.graphify`).
+- Call `graph_index` MCP tool (or run `memory graph index`) to compile a fresh symbol map in `.memory/graph-symbols.json`.
+
+```json
+{}
+```
+
+### Step 2: Code-Aware Retrieval Queries
+When querying memories for a specific function, class, or type, include the exact identifier name in your query:
+
+```json
+{
+  "query": "queryContext knapsack token scoring formula in retrieval.ts",
+  "project": "my-project",
+  "token_budget": 1500
+}
+```
+
+### Step 3: Multi-Factor AST Overlap Scoring Bonus
+The retrieval engine matches query tokens against indexed symbols (`entry.graph.symbol_names`), awarding up to **+0.2 graph bonus**:
+
+$$\text{Score} = 1.0 \times \text{Applicability} + \text{StatusBonus} + \text{VerificationBonus} + \mathbf{GraphBonus (+0.2)} + \text{TimeDecay}$$
+
+Symbol-matching architectural decisions and past fixes rank above generic prose matching.
+
+---
+
+## 🛡️ Invariant Rules for Agents
+
+- **Opt-In & Non-Blocking**: If no AST graph provider is installed, memory queries and captures fall back gracefully with zero behavioral disruption.
+- **Affected Paths**: Inspect `entry.graph.affected_paths` to discover related files that may be impacted by a refactor.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Check provider status (provider type, availability, revision, symbol count)
+memory graph status
+
+# Index codebase AST symbols and cache to .memory/graph-symbols.json
+memory graph index
+
+# Search with symbol terms
+memory search "queryContext" --token-budget 1500
+```

package/skills/muse-ground/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: muse-ground
+description: Pre-flight context and invariant grounding for AI coding agents. Retrieves Top-K relevant memories, active USER.md persona, and CURRENT.md working constraints at the start of any session or major task.
+---
+
+# 🎯 Muse Ground (`muse-ground`)
+
+> **When to use**: Execute at the start of every session, task initiation, or context switch before proposing code changes, creating plans, or executing refactors.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Query Context & Constraints
+Call the `get_context` MCP tool (or run `memory context "<query>"`) using your current task objective or keyword domain:
+
+```json
+{
+  "query": "authentication JWT expiration and database pool configuration",
+  "project": "my-project",
+  "token_budget": 2000
+}
+```
+
+### Step 2: Ingest Three-Tier Grounding Hierarchy
+The grounding response deterministically packages 3 critical layers in strict priority order:
+
+1. **`### User Profile & Preferences (USER.md)`**:
+   - Understand the user's role (`developer`, `designer`, `marketer`, `casual`, `custom`).
+   - Ground in explicit communication rules (e.g. terse output, runnable diffs, fail-fast mechanics).
+
+2. **`### Active Working Constraints (CURRENT.md)`**:
+   - Inspect immutable hard invariants (e.g. "Never commit secrets", "Preserve v1 backward compatibility").
+   - Review active session handoffs and in-flight checkpoints from previous agents.
+
+3. **`### Relevant Memories & Learned Patterns (Top-K)`**:
+   - Review past architectural decisions (`type: architecture`).
+   - Review previously solved edge-case bug fixes (`type: fix`).
+   - Avoid re-introducing known antipatterns or rejected hypotheses (`type: failure` / `status: rejected`).
+
+---
+
+## 🛡️ Invariant Rules for Agents
+
+- **Read Before Mutating**: Never edit code without first checking `CURRENT.md` and active constraints.
+- **Fail Fast on Missing Context**: If `get_context` reveals a conflicting historical decision, escalate or verify rather than blindly overriding.
+- **Tone Alignment**: Strictly mirror the persona defined in `USER.md`.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Retrieve top-ranked prompt context
+memory context "query terms" --token-budget 2000
+
+# Inspect active working constraints directly
+memory current get
+
+# Inspect active user persona profile
+memory user get
+```

package/skills/muse-wiki/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: muse-wiki
+description: Obsidian-compatible knowledge compounding and entity graph generation. Compiles confirmed memories into interlinked Markdown concept pages and tracks named entity co-occurrences.
+---
+
+# 📚 Muse Wiki (`muse-wiki`)
+
+> **When to use**: Execute at milestone completion, weekly review, or when synthesizing scattered memory units into a structured, readable documentation wiki.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Compile Knowledge Wiki
+Call the `memory_wiki_compile` MCP tool (or run `memory wiki compile`):
+
+```json
+{
+  "project": "my-project",
+  "min_cluster_size": 2
+}
+```
+
+This compiles confirmed memories into structured Obsidian Markdown files in `.memory/wiki/`:
+- **Concept Pages (`wiki/concepts/`)**: Clustered architectural concepts with bidirectional `[[concept-slug]]` wikilinks.
+- **Entity Pages (`wiki/entities/`)**: Extracted tools, frameworks, components, and libraries.
+- **Master Index (`wiki/index.md`)**: Table of contents mapping all domain topics.
+
+### Step 2: Query Wiki Concepts & Entity Graph
+- Call `memory_wiki_search` / `memory_wiki_get` to read synthesized domain documentation.
+- Call `memory_entities_search` / `memory_entities_get` to inspect entity co-occurrence networks (e.g. which libraries are frequently paired with specific architectures).
+
+---
+
+## 🛡️ Invariant Rules for Agents
+
+- **Confirmed Only**: Only `confirmed` memories are compiled into wiki pages to guarantee high signal and prevent draft noise.
+- **Dual Persistence**: Wiki pages are plain Markdown files with YAML frontmatter, fully editable in Obsidian, VS Code, or Cursor.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Compile confirmed memories into Obsidian-compatible wiki
+memory wiki compile
+
+# List compiled wiki pages
+memory wiki list
+
+# Read a specific concept page
+memory wiki show auth-patterns
+
+# Inspect entity relationships
+memory entities show nextjs
+memory entities related nextjs
+```