cogitation

Engram Cogitator

The Machine Spirit remembers what you forget.
(And unlike your da, it won't bring up that one time you dropped prod)

Persistent semantic memory for AI coding assistants.
By the grace of the Omnissiah, your decisions shall not be lost to the warp.

Works with: Claude Code, Cursor, Cline, Windsurf, and any MCP-compatible client

---

Quick Start (Solo Mode)

Step 1: Install the MCP server

curl -sSL https://raw.githubusercontent.com/MereWhiplash/engram-cogitator/main/install.sh | bash

Step 2: Install the cogitation plugin (in Claude Code)

/plugin marketplace add MereWhiplash/engram-cogitator
/plugin install cogitation@engram-cogitator

Step 3: Initialize your project

/cogitation:init

Prerequisites: Docker running. That's it.

---

What's Included

MCP Server (ec_* tools)

The memory backend. Provides ec_add, ec_search, ec_list, ec_invalidate for storing and retrieving semantic memories.

Cogitation Plugin (skills)

Opinionated development workflows that leverage EC's persistent memory.

The Development Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   /cogitation:init          (one-time project setup)                │
│         │                                                           │
│         ▼                                                           │
│   /cogitation:brainstorming (explore idea → design doc)             │
│         │                                                           │
│         ▼                                                           │
│   /cogitation:writing-plans (design doc → implementation plan)      │
│         │                                                           │
│         ▼                                                           │
│   /cogitation:executing-plans (plan → working code)                 │
│         │                                                           │
│         ▼                                                           │
│   /cogitation:finish        (verify, store learnings, merge)        │
│                                                                     │
│   /cogitation:audit         (periodic memory cleanup)               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Main Commands

/cogitation:init - First-time project setup

• Verifies EC connection is working
• Scaffolds docs/designs/ and docs/plans/ directories
• Configures test, build, and lint commands for your project
• Stores project config in EC for other skills to use

/cogitation:brainstorming - Turn ideas into designs

• Searches EC for prior decisions and patterns in related areas
• Creates a feature branch
• Guides you through requirements via Q&A
• Generates multiple approaches with tradeoffs
• Produces a design doc in docs/designs/YYYY-MM-DD-<topic>.md
• Stores key decisions in EC

/cogitation:writing-plans - Turn designs into plans

• Loads the design doc and relevant EC context
• Breaks work into small, testable batches (TDD-style)
• Each batch: write test → implement → verify
• Produces a plan in docs/plans/YYYY-MM-DD-<topic>.md
• Plans are detailed enough for zero-context execution

/cogitation:executing-plans - Turn plans into code

• Loads plan and EC context before each batch
• Executes batches with review checkpoints
• Runs tests after each batch
• Pauses for your approval before continuing
• Stores learnings discovered during implementation

/cogitation:finish - Complete the work

• Runs all verification (tests, lint, build)
• Reviews session for memories worth storing
• Presents merge options (squash, merge, rebase)
• Cleans up feature branch after merge

/cogitation:audit - Memory maintenance

• Lists all stored memories by type
• Finds duplicates and stale entries
• Presents cleanup recommendations
• Invalidates outdated memories

Additional Skills

These are invoked automatically by Claude based on context: