memory-journal-mcp 8.0.1 → 9.1.0

package/skills/adversarial-performance/references/audit-categories.md

@@ -1,462 +0,0 @@
-# Audit Categories
-
-Detailed reference for the 7 performance audit categories. Each category
-includes what to measure, anti-patterns, optimization patterns, and
-depth-specific considerations.
-
-Agent A (Profiler) uses this as a measurement checklist during Phase 1.
-Agent B (Stress Tester) uses it to construct worst-case scenarios in Phase 2.
-
----
-
-## Category 1 — Build Performance
-
-### What to Measure
-
-- Total TypeScript compilation time (`tsc --noEmit --diagnostics`)
-- Bundler build time (`npm run build`)
-- Files compiled and lines of code
-- Memory usage during compilation
-- Incremental vs. clean build times
-- Docker image build time (if containerized)
-
-### Anti-Patterns
-
-```typescript
-// Deep generic nesting — exponential type resolution
-type DeepPartial<T> = {
-  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
-} // Deeply nested usage causes slow compilation
-
-// Circular type references
-type A = { b: B }
-type B = { a: A } // Compiler struggles with these
-
-// Barrel re-exports pulling in entire dependency graph
-export * from './module-a'
-export * from './module-b'
-// Forces tsc to resolve everything even if only one export is used
-```
-
-### Optimization Patterns
-
-```typescript
-// Explicit exports instead of barrel wildcards
-export { SpecificType } from "./module-a";
-export { SpecificFunction } from "./module-b";
-
-// Project references for monorepo build parallelism
-// tsconfig.json
-{ "references": [{ "path": "./packages/core" }] }
-
-// Incremental compilation
-// tsconfig.json
-{ "compilerOptions": { "incremental": true, "tsBuildInfoFile": ".tsbuildinfo" } }
-```
-
-### Depth: Intensive
-
-- Profile individual file compilation times to find the slowest files
-- Analyze type complexity (deeply nested generics, conditional types)
-- Measure Docker layer cache hit rates
-- Compare clean vs. incremental build to validate caching effectiveness
-
----
-
-## Category 2 — Bundle & Output Analysis
-
-### What to Measure
-
-- Total output size (`dist/` or `build/`)
-- Top 5 largest output files by size
-- Source map presence and size in production
-- Number of output chunks (for code-split builds)
-- Tree-shaking effectiveness (are unused exports eliminated?)
-
-### Anti-Patterns
-
-```typescript
-// Importing entire library when only one function is needed
-import _ from 'lodash' // Pulls in ~600KB
-_.get(obj, 'path')
-
-// Dev dependency accidentally in production bundle
-import { faker } from '@faker-js/faker' // 3MB+ test utility
-
-// Source maps shipped to production
-// tsup.config.ts
-{
-  sourcemap: true
-} // Fine for dev, costly for production
-```
-
-### Optimization Patterns
-
-```typescript
-// Targeted imports
-import get from 'lodash/get' // ~1KB vs 600KB
-
-// External dependencies (not bundled)
-// tsup.config.ts
-{
-  external: ['better-sqlite3', 'sql.js']
-}
-
-// Source maps only in dev
-{
-  sourcemap: process.env.NODE_ENV !== 'production'
-}
-```
-
-### Depth: Intensive
-
-- Trace each large output file to its source to find bundling waste
-- Analyze tree-shaking failures (what's included but never called?)
-- Measure gzip/brotli compressed sizes for realistic transfer cost
-
----
-
-## Category 3 — Dependency Weight
-
-### What to Measure
-
-- Total production dependency count (direct + transitive)
-- Top 5 heaviest dependencies by install size
-- Duplicate packages (different versions of the same dep)
-- Dependency tree depth (deep trees increase install time and risk)
-- `devDependencies` accidentally in `dependencies`
-
-### Anti-Patterns
-
-```json
-// Heavy utility library for one function
-"dependencies": { "moment": "^2.30.0" }  // 300KB+ for date formatting
-
-// Duplicate versions in tree
-"better-sqlite3": "11.0.0"  // direct
-"some-plugin > better-sqlite3": "10.0.0"  // transitive duplicate
-
-// Dev dependency in prod
-"dependencies": { "@types/node": "^22.0.0" }  // Should be devDependencies
-```
-
-### Optimization Patterns
-
-```json
-// Lighter alternatives
-"dependencies": { "dayjs": "^1.11.0" }  // 2KB vs 300KB
-
-// Deduplication
-// npm dedupe
-
-// Correct dependency placement
-"devDependencies": { "@types/node": "^22.0.0" }
-```
-
-### Depth: Intensive
-
-- Calculate total `node_modules` size for production install
-- Compare each heavy dependency against lighter alternatives
-- Check for phantom dependencies (used but not declared — rely on hoisting)
-
----
-
-## Category 4 — Runtime Performance
-
-### What to Look For
-
-This is a **static analysis** category. Scan source code for patterns that
-cause runtime performance issues without running a profiler.
-
-- **Hot-path allocations** — object/array creation inside tight loops,
-  repeated `JSON.parse`/`JSON.stringify`, unnecessary spread operators in
-  iteration
-- **Missing early returns** — functions doing expensive work before checking
-  guard conditions
-- **Redundant computation** — values computed multiple times when they could
-  be cached or hoisted
-- **Blocking operations** — synchronous file I/O (`fs.readFileSync` in
-  request handlers), CPU-intensive loops without yielding, serial `await`
-  where parallel is safe
-- **Memory leaks** — event listeners not cleaned up, growing Maps/Sets
-  without eviction, closures capturing large scopes, timers without
-  `clearInterval`
-- **Startup cost** — heavy top-level initialization, eager loading of
-  rarely-used modules
-
-### Anti-Patterns
-
-```typescript
-// Object allocation in hot loop
-for (const row of rows) {
-  const result = { ...defaults, ...row } // New object every iteration
-  results.push(result)
-}
-
-// Serial await where parallel is safe
-const a = await fetchA()
-const b = await fetchB() // b doesn't depend on a — should be parallel
-
-// Sync file I/O in request handler
-app.get('/config', (req, res) => {
-  const config = fs.readFileSync('config.json') // Blocks event loop
-  res.json(JSON.parse(config))
-})
-
-// Missing early return
-function processItem(item) {
-  const expensive = computeExpensiveThing(item) // Done before validation
-  if (!item.isValid) return null // Wasted computation
-  return expensive
-}
-
-// Memory leak — growing Map without eviction
-const cache = new Map()
-function getUser(id) {
-  if (!cache.has(id)) cache.set(id, fetchUser(id)) // Never evicts
-  return cache.get(id)
-}
-```
-
-### Optimization Patterns
-
-```typescript
-// Reuse object shape
-const result = Object.create(null)
-for (const row of rows) {
-  Object.assign(result, defaults, row)
-  results.push({ ...result })
-}
-
-// Parallel await
-const [a, b] = await Promise.all([fetchA(), fetchB()])
-
-// Async file I/O with caching
-let configCache
-app.get('/config', async (req, res) => {
-  configCache ??= await fs.readFile('config.json', 'utf8')
-  res.json(JSON.parse(configCache))
-})
-
-// Early return before expensive work
-function processItem(item) {
-  if (!item.isValid) return null
-  return computeExpensiveThing(item)
-}
-
-// LRU cache with eviction
-import { LRUCache } from 'lru-cache'
-const cache = new LRUCache({ max: 1000, ttl: 60_000 })
-```
-
-### Depth: Intensive
-
-- Trace hot paths end-to-end (request → handler → query → response)
-- Analyze Big-O complexity of key algorithms
-- Check for event loop blocking using heuristic detection (sync I/O,
-  heavy computation, long-running regex)
-- Estimate cold start time (first request after process start)
-
----
-
-## Category 5 — Test Suite Performance
-
-### What to Measure
-
-- Total suite duration
-- Top 5 slowest test files (with durations)
-- Top 5 slowest individual tests (with durations)
-- Parallelization configuration (Vitest `pool`, `poolOptions`)
-- Test isolation overhead (setup/teardown time)
-
-### Anti-Patterns
-
-```typescript
-// Real I/O in unit tests
-test("fetches data", async () => {
-  const data = await fetch("https://api.example.com/data"); // Network I/O
-});
-
-// Heavy setup for simple assertions
-beforeEach(async () => {
-  await seedEntireDatabase(); // 500ms setup for a 10ms assertion
-});
-
-// Sequential tests that could parallelize
-// vitest.config.ts
-{ test: { pool: "forks", poolOptions: { forks: { singleFork: true } } } }
-```
-
-### Optimization Patterns
-
-```typescript
-// Mock external I/O
-vi.mock('node:fetch', () => ({ default: vi.fn() }))
-
-// Minimal setup — seed only what the test needs
-beforeEach(async () => {
-  await seedSingleTable('users', [testUser])
-})
-
-// Parallel execution
-// vitest.config.ts
-{
-  test: {
-    pool: 'threads'
-  }
-}
-```
-
-### Applicability
-
-If the project has no test suite, report this category as N/A.
-
----
-
-## Category 6 — Database & I/O Performance
-
-### What to Look For
-
-- **N+1 queries** — database queries executed inside loops instead of
-  batching
-- **Unbounded queries** — `SELECT *` without `LIMIT`, missing pagination
-- **Missing indexes** — filtered/joined columns without indexes
-- **Connection management** — pool sizing, connection leak risks, missing
-  timeouts
-- **Caching** — repeated identical queries without caching, stale TTLs
-- **Serialization overhead** — excessive object transformation between
-  layers, unnecessary deep cloning
-
-### Anti-Patterns
-
-```typescript
-// N+1 query
-const users = await db.query('SELECT * FROM users')
-for (const user of users) {
-  const orders = await db.query(`SELECT * FROM orders WHERE user_id = ?`, [user.id])
-  // Each iteration is a new query
-}
-
-// Unbounded query
-const allRows = await db.query('SELECT * FROM large_table') // No LIMIT
-
-// Unnecessary deep clone
-const copy = JSON.parse(JSON.stringify(largeObject)) // Expensive!
-```
-
-### Optimization Patterns
-
-```typescript
-// Batch query
-const users = await db.query('SELECT * FROM users')
-const userIds = users.map((u) => u.id)
-const orders = await db.query(
-  `SELECT * FROM orders WHERE user_id IN (${userIds.map(() => '?').join(',')})`,
-  userIds
-)
-
-// Bounded query with pagination
-const rows = await db.query('SELECT * FROM large_table LIMIT ? OFFSET ?', [100, offset])
-
-// Structured clone (faster than JSON roundtrip)
-const copy = structuredClone(largeObject)
-```
-
-### Applicability
-
-If the project doesn't interact with databases or perform significant I/O,
-report this category as N/A. Still check for file system operations and
-network calls.
-
----
-
-## Category 7 — Token & Context Efficiency
-
-### Applicability
-
-This category applies to **all project types** with graceful degradation:
-
-| Project Profile | Depth         | Rationale                              |
-| --------------- | ------------- | -------------------------------------- |
-| `mcp-server`    | Full          | Primary target — all checks apply      |
-| `web-app`       | Informational | Check API response verbosity           |
-| `cli-tool`      | Informational | Check output verbosity, help text size |
-| `library`       | Informational | Check type export complexity           |
-
-### What to Look For
-
-- **Verbose tool output** — tools returning full objects when summaries
-  suffice. Do `outputSchema` definitions constrain response size?
-- **Missing Code Mode** — servers with 15+ tools should offer sandboxed JS
-  execution for token-efficient multi-step operations (70–90% savings)
-- **Instruction bloat** — `instructions` field sending full documentation
-  instead of slim pointers to pull-based help resources
-- **Tool count** — 50+ tool servers without `--tool-filter` waste context
-  on unused tool definitions
-- **Redundant tools** — tools with significantly overlapping functionality
-- **Response padding** — success responses including unnecessary metadata,
-  empty arrays, or default values that could be omitted
-
-### Anti-Patterns
-
-```typescript
-// Tool returning everything — wastes tokens
-return {
-  success: true,
-  data: entireTable, // Could be thousands of rows
-  metadata: fullSchemaInfo, // Not requested
-  stats: computedStats, // Not requested
-}
-
-// Huge instructions field — pushed on every connection
-const INSTRUCTIONS = `Full 10-page documentation here...` // 5KB+
-
-// 170 tools, no filtering
-server.registerAllTools() // Client receives all 170 tool schemas
-```
-
-### Optimization Patterns
-
-```typescript
-// Constrained output — only what was asked for
-return {
-  success: true,
-  rows: data.slice(0, limit),
-  totalCount: data.length,
-  truncated: data.length > limit,
-}
-
-// Slim instructions + pull-based help resources
-const INSTRUCTIONS = 'Use sqlite://help for documentation.' // ~50 chars
-
-// Tool filtering
-// --tool-filter "core,json,codemode"  → 47 tools instead of 170
-```
-
-### MCP Server Checklist
-
-When the target is an MCP server, specifically verify:
-
-- [ ] `instructions` field is < 1KB (slim pointer, not full docs)
-- [ ] Help resources exist for pull-based documentation
-- [ ] `--tool-filter` is implemented for large tool counts
-- [ ] Code Mode (sandboxed JS) is available for multi-step operations
-- [ ] `outputSchema` constrains response shapes (no unbounded arrays)
-- [ ] Tools don't return redundant metadata by default
-- [ ] Progress notifications are used for long-running operations
-- [ ] Resources are used for large static data (schemas, configs)
-
----
-
-## Category Cross-Reference
-
-Quick lookup for which categories matter most by project profile:
-
-| Project Profile | Primary Categories | Secondary |
-| --------------- | ------------------ | --------- |
-| MCP Server      | 4, 6, 7            | 1, 3      |
-| Web App         | 1, 2, 4            | 3, 5      |
-| CLI Tool        | 1, 3, 4            | 5         |
-| Library         | 1, 2, 3            | 4         |
-| Data-heavy      | 4, 6               | 1, 3, 5   |
-| Test-heavy      | 5, 4               | 1         |

package/skills/adversarial-performance/references/copilot-performance-prompts.md

@@ -1,44 +0,0 @@
-# Copilot Performance Prompts
-
-Reference for Phase 4 of the adversarial performance protocol — the
-independent external validation pass using the GitHub Copilot CLI.
-
-## Prerequisites
-
-1. **GitHub CLI installed**: `gh --version` (v2.x+)
-2. **Authenticated**: `gh auth status` passing
-3. **Copilot available**: `gh copilot --version` — the `copilot` subcommand is built into modern `gh` CLI (no separate extension needed)
-
-If Copilot CLI is not available, skip Phase 4 gracefully.
-
-## Prompt Templates
-
-> **⚠️ CRITICAL — Non-Interactive Mode**: The `gh copilot` CLI must be run in
-> non-interactive mode using the `-p` (or `--prompt`) flag. Interactive mode
-> will hang indefinitely in an automated agent context. Use:
->
-> ```
-> gh copilot -p "<prompt>" --allow-tool "shell(find,cat,head,grep)"
-> ```
->
-> The `--allow-tool` flag grants Copilot read access to the repository files.
-
-- Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts (like Antigravity's 10s `WaitMsBeforeAsync` limit), allow the command to naturally fall into the background. Use the `schedule` tool or wait for the system notification to retrieve the results. Do not skip execution due to timeout constraints.
-
-## Parsing Copilot Output
-
-1. **Extract findings** — parse tables or numbered lists
-2. **Map to categories** — classify against the 7 audit categories
-3. **Quantify impact** — if Copilot didn't estimate improvement, add
-   your own estimates based on the code context
-4. **Deduplicate** — compare against Phase 2 findings
-5. **Disposition** — apply Accept/Reject/Modify/Defer from Phase 3
-
-## Prompt Selection Guide
-
-| Audit Depth | Project Profile | Prompts to Use                             |
-| ----------- | --------------- | ------------------------------------------ |
-| Scan        | Any             | Full Repository only                       |
-| Standard    | Non-MCP         | Full Repository + Dependencies             |
-| Standard    | MCP Server      | Full Repository + Dependencies + MCP Token |
-| Intensive   | Any             | All 3 prompts                              |

package/skills/adversarial-performance/references/copilot-usage.md

@@ -1,16 +0,0 @@
-# GitHub Copilot External Validation
-
-> **⚠️ CRITICAL — Non-Interactive Mode**: The `gh copilot` CLI must be run in
-> non-interactive mode using the `-p` (or `--prompt`) flag. Interactive mode
-> will hang indefinitely in an automated agent context. Use:
->
-> ```
-> gh copilot -p "Considering these standards from Phase 0 research: [insert findings]. <prompt>" --allow-tool "shell(find,cat,head,grep)"
-> ```
->
-> The `--allow-tool` flag grants Copilot read access to the repository files.
-> Always `Set-Location` (or `cd`) to the target repository before invoking.
->
-> **⚠️ TIMEOUT GUIDANCE**: Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts, use the `-s` flag or allow the command to naturally fall into the background.
-
-> **⚠️ CRITICAL — No Fabrication**: You MUST actually execute `gh copilot` commands. Do NOT fabricate or predict what Copilot would say.

package/skills/adversarial-performance/references/feedback-loop.md

@@ -1,177 +0,0 @@
-# Feedback Loop & Documentation
-
-Reference for journaling, cross-session learning, and retrospective patterns
-used throughout the adversarial performance protocol.
-
-## Journal Entry Templates
-
-Each phase creates a journal entry using `create_entry`. The structured
-entry types and tags enable precise retrieval and performance trend tracking
-across releases.
-
-### Phase 1 — Profiling
-
-```
-create_entry({
-  content: "# Performance Profile: [Repository Name]\n\n[full profiling content with baselines]",
-  entry_type: "perf_profile",
-  tags: ["adversarial-performance", "profile"],
-  project_number: <project number>
-})
-```
-
-### Phase 2 — Stress Test Review
-
-```
-create_entry({
-  content: "# Stress Test Review: [Repository Name]\n\nOverall Score: X/5.0 — Grade Y\n\n[findings table and scores]",
-  entry_type: "perf_stress_test",
-  tags: ["adversarial-performance", "stress-test"],
-  project_number: <project number>
-})
-```
-
-### Phase 3 — Optimization Plan
-
-```
-create_entry({
-  content: "# Optimization Plan: [Repository Name]\n\n[disposition table + projected improvements]",
-  entry_type: "perf_optimization",
-  tags: ["adversarial-performance", "optimization"],
-  project_number: <project number>
-})
-```
-
-### Phase 4 — Copilot Validation
-
-```
-create_entry({
-  content: "# Copilot Performance Validation: [Repository Name]\n\n[copilot findings + final dispositions]",
-  entry_type: "perf_copilot",
-  tags: ["adversarial-performance", "copilot"],
-  project_number: <project number>
-})
-```
-
-### Final Summary
-
-```
-create_entry({
-  content: "# Performance Audit Complete: [Repository Name]\n\nScore: X/5.0 (Grade Y)\nCritical: N, High: N, Moderate: N, Low: N\n\n## Baselines\n- Build: Xs\n- Bundle: XMB\n- Dependencies: N direct / M transitive\n- Tests: Xs\n\n## Key Findings\n- [top 3 findings]\n\n## Projected Improvements\n- [accepted optimizations with estimates]",
-  entry_type: "perf_audit_complete",
-  tags: ["adversarial-performance", "audit-complete", "session-summary"],
-  project_number: <project number>
-})
-```
-
-## Linking Entries
-
-```
-link_entries({
-  from_entry_id: <stress_test_entry_id>,
-  to_entry_id: <profile_entry_id>,
-  relationship_type: "references",
-  description: "Stress test review of profiling baselines"
-})
-
-link_entries({
-  from_entry_id: <optimization_entry_id>,
-  to_entry_id: <stress_test_entry_id>,
-  relationship_type: "evolves_from",
-  description: "Optimization plan based on stress test findings"
-})
-
-link_entries({
-  from_entry_id: <implementation_entry_id>,
-  to_entry_id: <optimization_entry_id>,
-  relationship_type: "implements",
-  description: "Performance optimization implementation"
-})
-
-link_entries({
-  from_entry_id: <current_audit_id>,
-  to_entry_id: <prior_audit_id>,
-  relationship_type: "evolves_from",
-  description: "Follow-up audit tracking performance evolution"
-})
-```
-
-## Cross-Session Learning
-
-### Find Prior Audits
-
-```
-search_entries({
-  query: "<repository name>",
-  entry_type: "perf_profile",
-  tags: ["adversarial-performance"]
-})
-```
-
-### Track Performance Trends
-
-Compare baseline measurements across audits to detect regressions:
-
-```
-search_entries({
-  query: "<repository name> baseline",
-  entry_type: "perf_audit_complete",
-  tags: ["adversarial-performance", "audit-complete"]
-})
-```
-
-### Find Recurring Bottleneck Patterns
-
-```
-search_entries({
-  query: "<pattern, e.g., 'N+1 query'>",
-  entry_type: "perf_stress_test",
-  tags: ["adversarial-performance"]
-})
-```
-
-### Cross-Project Performance Patterns
-
-```
-get_cross_project_insights({
-  query: "performance bottleneck",
-  tags: ["adversarial-performance"]
-})
-```
-
-## Session Retrospective
-
-### Retrospective Template
-
-```
-create_entry({
-  content: "# Performance Audit Retrospective: [Repository Name]\n\n## Key Insights\n- [What the Profiler missed that the Stress Tester caught]\n- [What Copilot caught that internal review missed]\n- [Optimization patterns worth institutionalizing]\n- [Baselines that proved accurate vs. misleading]\n\n## Metrics\n- Initial performance score: X/5.0 (Grade Y)\n- Final performance score: X/5.0 (Grade Y)\n- Stress test passes: N\n- Critical findings: N (optimized: N, deferred: N)\n- Projected total improvement: [summary]\n\n## Baseline Comparison (vs. prior audit)\n- Build time: Xs → Ys (Δ Z%)\n- Bundle size: XMB → YMB (Δ Z%)\n- Test duration: Xs → Ys (Δ Z%)\n\n## Process Improvements\n- [Categories to emphasize next time]\n- [New measurement methods to add]",
-  entry_type: "retrospective",
-  tags: ["adversarial-performance", "retrospective", "session-summary"],
-  project_number: <project number>
-})
-```
-
-## Tag Convention
-
-| Tag                       | Purpose                                        |
-| ------------------------- | ---------------------------------------------- |
-| `adversarial-performance` | All entries from this skill (primary filter)   |
-| `profile`                 | Phase 1 output                                 |
-| `stress-test`             | Phase 2 output                                 |
-| `optimization`            | Phase 3 output                                 |
-| `copilot`                 | Phase 4 output                                 |
-| `audit-complete`          | Final consolidated summary                     |
-| `retrospective`           | Post-cycle review                              |
-| `session-summary`         | Enables retrieval via session summary searches |
-
-## Entry Type Reference
-
-| Entry Type            | Phase | Description                          |
-| --------------------- | ----- | ------------------------------------ |
-| `perf_profile`        | 1     | Baselines and existing optimizations |
-| `perf_stress_test`    | 2     | Stress test findings with scores     |
-| `perf_optimization`   | 3     | Optimization plan with dispositions  |
-| `perf_copilot`        | 4     | Copilot validation findings          |
-| `perf_audit_complete` | Final | Consolidated audit summary           |
-| `retrospective`       | Post  | Session retrospective with metrics   |