CMP - Collective Memory Protocol

The Development Intelligence Layer - Persistent memory, cross-project learning, and multi-agent collaboration for AI-assisted development.

Philosophy

| Principle | Meaning | |-----------|---------| | Evidence > Assumptions | Never assume. Always verify. Read before writing. | | Cloud > Local | Memory lives in the cloud. Sessions are ephemeral, knowledge is permanent. | | Collective > Individual | One project's learnings benefit all projects. | | Continuity > Restarts | Work survives IDE restarts, machine changes, and agent switches. |

Features

Core

• Plans with Checkpoints - Persistent objectives with semantic matching and multi-agent handoffs
• ESLint Plugin - 11+ custom rules for code quality
• Task Tracking - Automatic task registration in database
• Idea Capture - Collect ideas and improvements during work
• Memory System - Session context and memory management
• Auto-Improvement - Pattern detection and ESLint rule generation
• Dashboard - Web UI for visualization
• MCP Server - Model Context Protocol integration
• Analytics - Usage tracking and insights

Cloud Infrastructure

• Turso (SQLite Edge) - Plans, tasks, improvements, memories
• Upstash Redis - Session cache, rate limiting, real-time sync
• Upstash Vector - Semantic search with embeddings
• Cloud Hooks - Session continuity across IDE restarts

Multi-Agent Continuity (v2.5.0+)

• Plan Detection - Semantic matching finds related plans at session start
• Checkpoints - Save points that record progress, decisions, and next steps
• Agent Handoffs - One agent can resume where another left off
• Cross-Session - Plans persist across IDE restarts and machine changes

Cloud Quick Start

import { cloud } from 'cmp-standards'

// Initialize cloud services
await cloud.init()

// Start work session
const session = await cloud.startWorkSession('MYPROJECT')
console.log(`Active tasks: ${session.activeTasks.length}`)

// Start task
const taskId = await cloud.startTask('MYPROJECT', session.sessionId, {
  title: 'Implement feature X',
  plan: ['Step 1', 'Step 2'],
  domain: 'features'
})

// Complete task (requires at least 1 improvement)
await cloud.completeTask(taskId, {
  result: 'success',
  improvements: [{
    area: 'features',
    title: 'Add caching',
    description: 'Could cache API responses',
    priority: 'medium'
  }],
  lessons: ['Pattern X works better']
})

Environment Variables

# Turso (SQLite Edge)
TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-token

# Upstash Redis
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token

# Upstash Vector
UPSTASH_VECTOR_REST_URL=https://your-vector.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your-token

Installation

npm install cmp-standards

Quick Start

# Initialize in project
cmp-standards init --system MYPROJECT --name "My Project"

# Check status
cmp-standards status

# Start dashboard
cmp-standards dashboard

CLI Commands

cmp-standards init

Initialize the system in current project.

cmp-standards init [options]

Options:
  -s, --system <system>  System identifier (SWARMSCALE, PANEL)
  -n, --name <name>      Project name
  -f, --force            Overwrite existing configuration

cmp-standards generate

Generate embedding registry from documentation.

cmp-standards generate [options]

Options:
  -i, --incremental     Only update changed files
  --files <files>       Specific files (comma-separated)

cmp-standards scan

Scan codebase for patterns.

cmp-standards scan [options]

Options:
  -d, --dir <directory>   Directory to scan (default: src)
  -t, --threshold <n>     Pattern threshold (default: 3)

cmp-standards improve

Run auto-improvement for triggered patterns.

cmp-standards improve [options]

Options:
  --dry-run              Show without making changes
  -p, --pattern <id>     Specific pattern to improve

cmp-standards status

Show memory system status.

cmp-standards dashboard

Start the memory dashboard web UI.

cmp-standards dashboard [options]

Options:
  -p, --port <port>  Port to run on (default: 3847)
  --no-open          Don't open browser automatically

cmp-standards analytics

Show analytics and system health.

cmp-standards analytics [options]

Options:
  -p, --period <period>  Time period (day, week, month)
  --json                 Output as JSON

cmp-standards feedback

View feedback statistics.

cmp-standards mcp

Start the MCP server for Claude integration.

Workflow Commands

cmp-standards tasks

View and manage tasks.

cmp-standards tasks [options]

Options:
  -a, --all              Show all tasks including completed
  -l, --limit <number>   Limit number of tasks (default: 10)

cmp-standards ideas

View captured ideas.

cmp-standards ideas [options]

Options:
  -c, --category <cat>   Filter by category (feature, refactor, bug, optimization, documentation)
  -p, --priority <pri>   Filter by priority (high, medium, low)
  -l, --limit <number>   Limit number of ideas (default: 20)

cmp-standards improvements

View suggested improvements.

cmp-standards improvements [options]

Options:
  -t, --type <type>      Filter by type (code_quality, performance, security, ux, architecture)
  -e, --effort <effort>  Filter by effort (small, medium, large)
  -l, --limit <number>   Limit number (default: 20)

cmp-standards plan

Manage work plans.

cmp-standards plan [options]

Options:
  -s, --status           Show current plan status
  -c, --complete         Complete current task
  -n, --next             Move to next task
  -h, --history          Show plan history

cmp-standards capture <text>

Quick capture an idea or improvement. Auto-categorizes based on content.

cmp-standards capture "Consider adding caching to API calls"

cmp-standards export

Export ideas and improvements as markdown.

cmp-standards export [options]

Options:
  -o, --output <file>    Output file (default: IDEAS_AND_IMPROVEMENTS.md)

Architecture

cmp-standards
├── src/
│   ├── hooks/
│   │   ├── session-start.ts      # Context loader on session start
│   │   ├── pre-tool-use.ts       # Guards + embedding injection
│   │   ├── post-tool-use.ts      # Record changes after Edit/Write
│   │   └── memory-checkpoint.ts  # Record learnings after changes
│   ├── eslint/
│   │   ├── index.ts              # ESLint plugin entry
│   │   ├── rules/                # Custom ESLint rules
│   │   └── config-builder.ts     # Dynamic config generation
│   ├── services/
│   │   ├── TaskTracker.ts        # Task tracking
│   │   ├── IdeaCollector.ts      # Idea/improvement capture
│   │   ├── WorkPlanManager.ts    # Work plan management
│   │   └── ...                   # Other services
│   ├── registry/
│   │   ├── generator.ts          # Parse docs → embeddings
│   │   └── embeddings.ts         # OpenAI/Gemini embedding service
│   ├── auto-improve/
│   │   ├── pattern-detector.ts   # Detect repeated violations
│   │   └── eslint-generator.ts   # Generate ESLint rules
│   ├── db/
│   │   ├── client.ts             # DEV_Items database client (mock)
│   │   └── drizzle-client.ts     # Real Drizzle ORM client
│   ├── mcp/
│   │   └── server.ts             # MCP server for Claude tools
│   ├── dashboard/
│   │   ├── server.ts             # Express dashboard server
│   │   └── ui.ts                 # React UI generator
│   ├── utils/
│   │   ├── config.ts             # Configuration management
│   │   ├── paths.ts              # Path utilities with traversal protection
│   │   └── git.ts                # Safe git operations (simple-git)
│   ├── types/
│   │   └── index.ts              # Type definitions
│   ├── cli/
│   │   └── index.ts              # CLI commands
│   └── index.ts                  # Main exports

Configuration

.claude/memory-config.json

{
  "system": "SWARMSCALE",
  "projectName": "SwarmScale",
  "domains": ["video-studio", "avatars", "campaigns"],
  "guards": {
    "enabled": true,
    "rules": [
      {
        "id": "schema-protection",
        "type": "block",
        "filePattern": "src/server/schema/auth.ts",
        "message": "PANEL_* tables are READ-ONLY"
      }
    ]
  },
  "embedding": {
    "enabled": true,
    "threshold": 0.60,
    "maxSections": 3
  },
  "autoImprovement": {
    "enabled": true,
    "violationThreshold": 3,
    "generateEslintRules": true
  }
}

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [{
          "type": "command",
          "command": "npx tsx node_modules/cmp-standards/dist/hooks/pre-tool-use.js"
        }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "npx tsx node_modules/cmp-standards/dist/hooks/session-start.js"
        }]
      }
    ]
  },
  "plugins": {
    "cmp-standards": {
      "version": "2.0.0",
      "enabled": true
    }
  }
}

Hooks

SessionStart Hook

Executes on session start:

1. Detects module from git diff (last 24h)
2. Queries DEV_Items for relevant memories
3. Returns formatted context

import { SessionStartHook } from 'cmp-standards/hooks'

const hook = new SessionStartHook()
const result = await hook.execute()
// result.context contains session context

PreToolUse Hook

Executes before Edit/Write/Task tools:

1. Edit/Write: Validates against guard rules
2. Task: Injects relevant knowledge via embeddings

import { PreToolUseHook } from 'cmp-standards/hooks'

const hook = new PreToolUseHook()
const result = await hook.execute({
  tool_name: 'Edit',
  parameters: { file_path: 'src/file.ts', new_string: '...' }
})

if (result.mode === 'block') {
  // Guard violation - block operation
}

ESLint Plugin

The package includes a custom ESLint plugin with 11+ rules.

Using the ESLint Plugin

// eslint.config.mjs
import cmpStandards from 'cmp-standards/eslint'

export default [
  ...cmpStandards.configs.recommended,
]

Dynamic Configuration

import { generateConfig } from 'cmp-standards/eslint'

// Generate config based on project structure
const config = await generateConfig(process.cwd())

Auto-Improvement

Pattern Detection

Built-in patterns detected:

• any-type - Using any type
• console-log - Console.log in production
• eslint-disable - ESLint disable comments
• hardcoded-string - UI strings not using i18n
• direct-db-query - Database queries in components
• inline-style - Inline styles instead of Tailwind

ESLint Rule Generation

When a pattern is detected 3+ times:

# Scan for patterns
cmp-standards scan

# Output:
# any-type [high]
#    Count: 5, Files: 3
# Patterns ready for auto-improvement

# Generate ESLint rule
cmp-standards improve

# Creates: eslint-plugin-charter/rules/no-any-type.js

Programmatic Usage

import {
  loadConfig,
  PatternDetector,
  ESLintGenerator,
  RegistryGenerator
} from 'cmp-standards'

// Load config
const config = await loadConfig(process.cwd())

// Detect patterns
const detector = new PatternDetector(config)
const patterns = detector.scan(fileContent, filePath)
const results = detector.getResults()

// Generate ESLint rules
const generator = new ESLintGenerator()
await generator.generateAllRules(results.triggered)

// Generate registry
const registry = new RegistryGenerator()
await registry.generate()

System Isolation

Data is isolated by system field in DEV_Items:

| System | Project | |--------|---------| | SWARMSCALE | SwarmScale | | PANEL | TheCharterPanel | | ECOSYSTEM | Cross-project |

Always filter by system:

// Correct
db.select().from(devItems).where(eq(devItems.system, 'SWARMSCALE'))

// Wrong - returns ALL projects' data
db.select().from(devItems)

Security Features

Path Traversal Protection

All path operations are validated to prevent directory traversal attacks:

import { validateSafePath, safeJoin } from 'cmp-standards'

// Throws PathTraversalError if path escapes base
validateSafePath(projectRoot, userPath)

// Safe path joining with validation
const safePath = safeJoin(projectRoot, 'subdir', filename)

Safe Git Operations

Git operations use simple-git instead of shell commands to prevent command injection:

import { getCurrentBranch, getRecentChanges } from 'cmp-standards'

// Safe - uses simple-git internally
const branch = await getCurrentBranch(projectRoot)
const changes = await getRecentChanges(projectRoot, { commits: 10 })

Environment Variables

# Required for embedding generation
OPENAI_API_KEY=sk-...      # Preferred
GEMINI_API_KEY=...         # Fallback

# Optional
MEMORY_DEBUG=true          # Enable debug logging

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Link for local development
npm link

MCP Server

The MCP (Model Context Protocol) server exposes memory tools that Claude can use directly:

# Start MCP server
cmp-standards mcp

Available Tools:

• memory_search - Search memories by query
• memory_write - Write new memory/learning
• memory_list - List recent memories
• pattern_check - Check for detected patterns
• pattern_report - Report a new pattern occurrence
• session_context - Get current session context
• feedback_submit - Submit feedback on a memory

Dashboard

Start the standalone web dashboard:

cmp-standards dashboard
# Opens http://localhost:3847

Features:

• View all memories with search and filtering
• Browse detected patterns
• See session history
• Submit feedback on memories
• Create new memories
• View analytics and system health

Database Configuration

Set environment variables for database connection:

DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=your-password
DATABASE_NAME=metanautical

License

MIT - Carlos Martin Pavon