claude-memory

A lightweight machine state scanner that generates compact context files for AI coding assistants like Claude Code.

Problem: Every new conversation with an AI assistant starts cold. It doesn't know what projects you're running, what's in cron, what Docker containers are up, or where your GAMEPLANs live.

Solution: claude-memory scans your machine and generates a single machine-state.md file that gives the AI full context in seconds — not minutes of back-and-forth questions.

What it scans

• Project directories — detects language, frameworks, config files
• GAMEPLANs — reads the first 15 lines of each project's GAMEPLAN.md
• Git status — last commit message and how recent
• Cron jobs — maps scheduled tasks to their projects
• Docker containers — what's running and on which ports

Quick Start

# Clone
git clone https://github.com/prime001/claude-memory.git
cd claude-memory

# Install
pip install -r requirements.txt

# Run the setup wizard — it finds your projects automatically
python configure.py

# That's it. machine-state.md is ready and Claude Code is configured.

The setup wizard:

1. Scans common directories (/opt, /home, /var/www, ~/projects, etc.)
2. Shows you what it found and lets you pick which to track
3. Lets you add custom directories
4. Generates config.yaml and runs the first scan
5. Connects to Claude Code (MCP server or CLAUDE.md — your choice)

To re-run setup later: python configure.py --reset

Connecting to Claude Code

The setup wizard offers two integration methods:

Option 1: MCP Server (recommended)

Claude automatically gets machine context when you ask about your projects. The setup wizard handles everything, but here's the manual config:

# Install MCP dependency
pip install mcp[cli]

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "python3",
      "args": ["/path/to/claude-memory/mcp_server.py"]
    }
  }
}

Then ask Claude: "What's on this machine?" or "What projects do we have?"

The MCP server exposes two tools:

• get_machine_state — returns full context, auto-refreshes if >1 hour old
• refresh_machine_state — forces a fresh scan

Option 2: CLAUDE.md (zero dependencies)

No MCP needed. Add one line to your CLAUDE.md:

At the start of a conversation, read /path/to/claude-memory/machine-state.md for machine context.

Claude will read the file when it needs context about your machine.

Option 3: Cron + manual

Keep the state fresh and read it when needed:

# Refresh every hour
0 * * * * cd /path/to/claude-memory && python3 scanner.py

# Or refresh before starting Claude Code
python3 scanner.py && claude

Configuration

Edit config.yaml to point at your directories:

output: ./machine-state.md

scan:
  - name: "My Projects"
    path: /home/user/projects
    depth: 1
    exclude:
      - node_modules
      - .git

  - name: "Web Sites"
    path: /var/www
    depth: 1

gameplan_max_lines: 15

Output Formats

# Markdown (default — optimized for LLM context windows)
python scanner.py

# JSON (for programmatic use)
python scanner.py --json

# Custom output path
python scanner.py --output ~/my-state.md

How it works

configure.py      Interactive wizard — discovers dirs, builds config, connects to Claude
scanner.py        Scans projects, cron, Docker, git — outputs machine-state.md
mcp_server.py     MCP server — Claude auto-loads context via tools
config.yaml       Your scan configuration (generated by configure.py)
machine-state.md  The output — compact machine context for AI consumption

1. Walks each configured directory (1 level deep by default)
2. Detects project type by checking for package.json, requirements.txt, go.mod, Dockerfile, etc.
3. Reads the first 15 lines of GAMEPLAN.md if present
4. Checks git for last commit info
5. Parses crontab -l and maps jobs to projects
6. Lists running Docker containers
7. Outputs a compact Markdown file designed to fit in ~2-3K tokens

What's a GAMEPLAN.md?

A GAMEPLAN.md is a project status file that lives in the root of each project. claude-memory reads the first 15 lines for a quick summary. If your projects don't have them, claude-memory still works — it just won't have GAMEPLAN summaries.

Example GAMEPLAN.md:

# My Project — GAMEPLAN

## Status
Phase: In progress
Progress: 60%

## What It Is
Brief description of the project.

## Next Actions
- [ ] Ship feature X
- [ ] Fix bug Y
- [x] Deploy to staging

Why Markdown over a database?

• Claude Code can read it directly — no adapter needed
• Collapsible <details> blocks keep GAMEPLAN summaries compact
• Tables are scannable — the AI finds what it needs fast
• No database overhead, no running processes (unless you use MCP)
• Works on any machine with Python 3.8+ and PyYAML

License

MIT