working-memory-0.2.2 is not a library.

wm — Working Memory for AI Coding Assistants

wm automatically captures tacit knowledge from your coding sessions and surfaces relevant context for each new task. It's the memory layer that helps AI assistants learn how you work.

Supported platforms:

Claude Code - Full support via plugin
OpenAI Codex CLI - Alpha support via skill (agent-invoked)

The Problem

LLMs have amnesia. Every conversation starts fresh. The patterns you've established, the constraints you've discovered, the preferences you've revealed—all forgotten.

You end up repeating yourself:

"Remember, we always use X pattern here"
"Don't forget the constraint about Y"
"I prefer Z approach for this kind of problem"

The Solution

wm runs silently in the background:

Extract: After each conversation turn, captures tacit knowledge—the wisdom that emerges from how you work, not just what you say
Compile: Before each new prompt, filters accumulated knowledge for relevance and injects it as context

The result: AI assistants that remember your patterns across sessions.

What Gets Captured

Tacit knowledge is the unspoken wisdom in how someone works:

Rationale behind decisions (WHY this approach, not just WHAT was done)
Paths rejected and why (the judgment in pruning options)
Constraints discovered through friction
Preferences revealed by corrections
Patterns followed without stating

Not captured:

What happened ("Fixed X", "Updated Y")
Explicit requests or questions
Tool outputs or code snippets
Content from CLAUDE.md (already explicit)

Quickstart: Claude Code

Prerequisites

Claude Code CLI
superego (optional, but recommended for extraction triggers)

Option 1: Homebrew (macOS)

brew tap cloud-atlas-ai/wm
brew install wm

Option 2: Cargo (all platforms)

cargo install wm

Option 3: From Source

git clone https://github.com/cloud-atlas-ai/wm.git
cd wm
cargo install --path .

Install the Claude Code Plugin

claude plugin install wm

Initialize in Your Project

cd /your/project
wm init

This creates a .wm/ directory to store accumulated knowledge.

Quickstart: OpenAI Codex CLI (Alpha)

Codex support uses agent skills that can be invoked at decision points. Most features work, but session auto-discovery is limited due to Codex's different session storage format.

What works:

✅ Manual knowledge capture/review (state.md, working_set.md)
✅ Dive prep with context gathering
✅ Compress and pause operations
⚠️ Distill requires manual transcript paths (no auto-discovery yet)

# 1. Install the binary (choose one)
brew install cloud-atlas-ai/wm/wm           # macOS
cargo install wm                            # All platforms

# 2. Install the skills
mkdir -p ~/.codex/skills
ln -s /path/to/wm/plugin ~/.codex/skills/wm

# Or download agents individually:
mkdir -p ~/.codex/skills/wm/agents
BASE_URL="https://raw.githubusercontent.com/cloud-atlas-ai/wm/main/plugin/agents"
curl -L -o ~/.codex/skills/wm/agents/dive-prep.md $BASE_URL/dive-prep.md
curl -L -o ~/.codex/skills/wm/agents/review.md $BASE_URL/review.md
curl -L -o ~/.codex/skills/wm/agents/distill.md $BASE_URL/distill.md
curl -L -o ~/.codex/skills/wm/agents/compress.md $BASE_URL/compress.md
curl -L -o ~/.codex/skills/wm/agents/pause.md $BASE_URL/pause.md

Available Agent Skills:

Skill	Support	When to Use
`$wm:dive-prep`	✅ Full	Prepare focused work session with intent, context, and workflow
`$wm:review`	✅ Full	Review accumulated knowledge and current context
`$wm:compress`	✅ Full	Synthesize state.md to higher-level abstractions
`$wm:pause`	✅ Full	Pause/resume operations (extract, compile, or both)
`$wm:distill`	⚠️ Manual	Batch extract (requires manual transcript paths)

Typical Workflows:

# Session start - prepare dive context
$wm:dive-prep --intent fix

# Mid-session - review what wm knows
$wm:review

# Maintenance - compress accumulated knowledge
$wm:compress

# Sensitive work - pause extraction
$wm:pause extract

# Manual extraction from Codex session (since auto-discovery isn't supported yet)
# Find your sessions:
ls ~/.codex/sessions/2026/01/*/rollout-*.jsonl
# Extract from specific transcript:
wm extract --transcript ~/.codex/sessions/2026/01/06/rollout-<timestamp>-<uuid>.jsonl

Why limited session discovery?

Codex stores sessions in ~/.codex/sessions/YYYY/MM/DD/ with different naming and structure than Claude Code's ~/.claude/projects/<project-id>/. Auto-discovery support for Codex sessions is tracked in #11.

Manual Commands:

All CLI commands work normally: wm init, wm show state, wm show working, etc.

See plugin/agents/ for detailed documentation on each skill.

Usage

Once installed, wm works automatically:

You write prompts → wm injects relevant context
You work with Claude → conversation happens normally
Turn ends → wm extracts any tacit knowledge learned

Manual Commands

# View accumulated knowledge
wm show state

# View what context would be injected
wm show working

# List all sessions
wm show sessions

# View session-specific working set
wm show working --session-id <id>

# Manually trigger extraction
wm extract

# Manually compile for a specific intent
wm compile --intent "implement authentication"

# Compress state.md (synthesize to higher abstractions)
wm compress

Compressing Knowledge

Over time, state.md accumulates knowledge and can grow unwieldy. The compress command distills it down by:

Merging related items into broader principles
Abstracting specific instances into general patterns
Removing obsolete or superseded knowledge
Preserving critical constraints and preferences

wm compress
# Compressed: 42 → 18 lines (57% reduction)
# Backup saved to .wm/state.md.backup

Run periodically when state feels bloated, not after every session.

Dive Sessions

A dive is a focused work session with explicit grounding. The metaphor: you don't just splash around—you dive into work with a clear purpose, knowing what you're after and what constraints apply.

Without a dive, AI sessions often drift:

You start coding without clarity on the goal
Constraints surface mid-work ("oh wait, we can't do that because...")
Related knowledge sits unused because nothing surfaced it
The session ends without capturing what was learned

With a dive, you start grounded:

Intent is explicit (fix, plan, explore, review, ship)
Context is curated (relevant knowledge, constraints, mission)
Workflow is suggested (what steps this intent typically follows)
Focus is documented (what specifically you're working on)

This isn't overhead—it's the 30 seconds of setup that saves 30 minutes of drift.

The `/dive-prep` Skill

Invoke /dive-prep in Claude Code to prepare a focused work session:

/dive-prep                          # Interactive - prompts for intent
/dive-prep --intent fix             # Fix a bug
/dive-prep --intent plan            # Design an approach
/dive-prep --intent explore         # Understand something
/dive-prep --intent review          # Reflect on recent work
/dive-prep --intent ship            # Get something deployed

What it does:

Detects context — Reads CLAUDE.md, git state, existing .wm/ knowledge
Checks for OH — If Open Horizons MCP is connected, offers to link to an endeavor for strategic context (missions, guardrails, learnings)
Asks for intent — If not provided, prompts for what you're trying to accomplish
Builds workflow — Suggests steps based on intent type
Writes manifest — Creates .wm/dive_context.md with curated grounding

With Open Horizons (recommended):

/dive-prep --intent fix --oh bd9d6ace

OH provides the strategic layer: why you're doing this (mission), what not to do (guardrails), and what you've learned (metis).

Without OH:

/dive-prep --intent explore
# Prompts: "What are you exploring?"

Still valuable—you get explicit intent, workflow guidance, and documented focus.

The `wm dive` Commands

Manage dive context directly:

wm dive load <pack-id>    # Load a pre-built dive pack from OH
wm dive show              # Display current dive context
wm dive clear             # Remove dive context

Dive packs are curated context bundles stored in Open Horizons. They're useful for recurring work patterns—load a pack instead of rebuilding context each time.

Configuration:

# Set OH API key (required for wm dive load)
export OH_API_KEY=your-key

# Or configure in ~/.config/openhorizons/config.json:
{
  "api_key": "your-key",
  "api_url": "https://app.openhorizons.me"
}

Batch Distillation

The distill command extracts knowledge from all your Claude Code sessions at once, instead of per-turn extraction:

wm distill                    # Process all sessions
wm distill --dry-run          # Preview what would be processed
wm distill --force            # Re-extract even cached sessions

How it works:

Discovers sessions — Finds all Claude Code transcripts for this project
Extracts incrementally — Caches results, only processes new/changed sessions
Accumulates knowledge — Writes raw extractions to .wm/distill/raw_extractions.md

When to use:

Initial setup: extract knowledge from existing sessions
Periodic catchup: if per-turn extraction was paused
Audit: see what knowledge exists across all sessions

Output:

.wm/distill/
├── raw_extractions.md    # Accumulated knowledge from all sessions
├── cache.json            # Extraction cache (enables incremental runs)
└── errors.log            # Any extraction failures

Pause and Resume

Temporarily disable wm operations without uninstalling:

wm pause                  # Pause both extract and compile
wm pause extract          # Pause only extraction
wm pause compile          # Pause only context injection

wm resume                 # Resume both operations
wm resume extract         # Resume only extraction
wm resume compile         # Resume only context injection

wm status                 # Show current state

When to use:

Sensitive work: Pause extraction when working on confidential code
Debugging: Isolate issues by disabling one operation
Performance: Skip context injection on simple tasks

Debugging

# Watch hooks fire in real-time
tail -f .wm/hook.log

# Check what's being captured
cat .wm/state.md

How It Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Session                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [User Prompt]                                              │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────┐                                        │
│  │ wm compile      │◄── Reads state.md                      │
│  │ (hook)          │    Filters for relevance               │
│  └────────┬────────┘    Injects as context                  │
│           │                                                 │
│           ▼                                                 │
│  [Claude Processes with Context]                            │
│           │                                                 │
│           ▼                                                 │
│  ┌─────────────────┐                                        │
│  │ sg evaluate     │◄── Superego evaluates turn             │
│  │ (stop hook)     │    Calls wm extract in background      │
│  └────────┬────────┘                                        │
│           │                                                 │
│           ▼                                                 │
│  ┌─────────────────┐                                        │
│  │ wm extract      │◄── Reads transcript                    │
│  │ (background)    │    Extracts tacit knowledge            │
│  └─────────────────┘    Updates state.md                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Storage

.wm/
├── state.md              # Accumulated tacit knowledge (the "memory")
├── working_set.md        # Last compiled context
├── hook.log              # Debug log
└── sessions/
    └── <session-id>/     # Per-session state (prevents cross-session bleed)

Integration with Superego

wm is designed to work with superego, a metacognitive advisor for AI assistants. When both are installed:

superego evaluates Claude's work and provides feedback
superego's stop hook triggers wm extraction in the background
wm captures knowledge, superego captures concerns—complementary roles

They compose via shell calls with no shared state (Unix philosophy).

Configuration

Environment Variables

Variable	Purpose
`WM_DISABLED=1`	Skip all wm operations
`CLAUDE_PROJECT_DIR`	Project root (auto-set by Claude Code)

What to Expect

First few sessions: Little or no knowledge captured (normal)
Over time: Patterns accumulate in state.md
Context injection: Only relevant items surface per-task
LLM costs: Each extract/compile makes one LLM call (~$0.01-0.05)

Troubleshooting

Hooks not firing

Check if wm is in PATH: which wm
Check if .wm/ exists in project

Reinstall plugin after updates:

claude plugin uninstall wm
claude plugin install ./plugin
# Restart Claude Code

No knowledge being captured

Most sessions genuinely have no tacit knowledge worth capturing
Check .wm/hook.log for extraction activity
Verify superego is installed (it triggers extraction)

State.md has wrong content

System reminders (CLAUDE.md content) should be stripped
If seeing explicit instructions, check transcript reader is up to date

License

Source-available. See LICENSE.md for details.

Part of Cloud Atlas AI

wm is part of the Cloud Atlas AI ecosystem:

Open Horizons — Strategic alignment platform
superego — Metacognitive advisor
wm — Working memory (this project)
oh-mcp-server — MCP bridge to Open Horizons

working-memory 0.2.2