Memo

AI-powered codebase memory for coding agents. Watches file changes and maintains .memo documentation automatically.

Why Memo?

Vibe coding with AI agents across multiple sessions evolves fast—too fast for humans to keep up. Projects spiral out of control due to lack of global consistency: models can't read the entire codebase in one pass, and neither can humans.

Inspired by traditional code indexing, Memo maintains a semantic index specifically for coding agents, capturing architecture and key decisions. This enables:

• "Summarize this repo" — No need to read every file. Memo provides instant context.
• Preserve design decisions — Trade-offs and constraints are recorded once, no need to repeat every session.
• Holistic refactoring — After modifying a module, agents can update related code across the project, even connections that static analysis can't detect.
• Beyond coding: Large document navigation — Find related content without scanning everything.

Benchmark

Evaluated on a subset of SWE-bench Lite (23 instances, limited by time&token):

performance_analysis_final.png

Key findings:

• 4× pass rate improvement (4.3% → 17.4%)
• 15% faster inference (212s → 180s per instance)
• Memo index generation is one-time cost, amortized across tasks

Installation

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/YoungY620/memo/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/YoungY620/memo/main/install.ps1 | iex

Update

Run the same installation command to update to the latest version. Memo also checks for updates automatically on startup.

Build from Source

git clone https://github.com/YoungY620/memo.git
cd memo
make install  # installs to ~/.local/bin

Usage

Memo has three commands:

Watch Mode (default)

Continuously monitors file changes and updates .memo/index:

memo                          # watch current directory
memo watch                    # explicit watch command
memo watch -p /path/to/repo   # watch specific directory
memo watch --skip-scan        # skip initial full scan (when index is up-to-date)

Scan Mode

Analyzes all files once, updates index, then exits. Useful for CI or initial setup:

memo scan
memo scan -p /path/to/repo

MCP Mode

Starts an MCP server for AI agents to query the index. Requires an existing .memo/index (run watch/scan first):

memo mcp
memo mcp -p /path/to/repo

Global Options

memo --version                # print version
memo --help                   # show help
memo <command> --help         # show command-specific help

Command-Specific Options

# watch and scan commands
memo watch -c config.yaml     # custom config file
memo watch --log-level debug  # log level: error/notice/info/debug

Configuration

Create config.yaml:

log_level: info  # error, notice, info, debug

watch:
  ignore_patterns:
    - ".git"
    - "node_modules"
    - ".memo"
    - "*.log"
  debounce_ms: 5000    # 5s quiet period
  max_wait_ms: 300000  # 5min max wait

MCP Integration

Memo exposes .memo/index to AI agents via MCP protocol:

• memo_list_keys — List keys at a JSON path
• memo_get_value — Get value at a JSON path

Quick Setup (auto-install)

This config auto-installs memo on first use. No pre-installation required.

Linux / macOS:

{
  "mcpServers": {
    "memo": {
      "command": "sh",
      "args": ["-c", "eval \"$(curl -fsSL https://raw.githubusercontent.com/YoungY620/memo/main/run-mcp.sh 2>/dev/null || echo '')\""]
    }
  }
}

Windows (PowerShell):

{
  "mcpServers": {
    "memo": {
      "command": "powershell",
      "args": ["-Command", "& { try { iex (irm 'https://raw.githubusercontent.com/YoungY620/memo/main/run-mcp.ps1') } catch { if (Get-Command memo -ErrorAction SilentlyContinue) { & memo mcp @args } else { throw 'memo not found and install failed' } } }"]
    }
  }
}

Already Installed

If memo is already installed and in your PATH:

{
  "mcpServers": {
    "memo": {
      "command": "memo",
      "args": ["mcp"]
    }
  }
}

Typical Workflow

1. Start watcher (keeps index updated as you code):

   cd /path/to/project && memo   # or: memo watch -p /path/to/project

2. Configure AI agent with one of the MCP configs above.

3. Query via agent:

   kimi
   > Summarize this repo

Note: If the index hasn't been built yet, tool calls return a helpful error message suggesting to run memo scan or memo watch — the MCP server stays running and won't crash the agent.

Entire.io Integration (Optional)

Memo can analyze Entire.io checkpoint data to capture AI coding session history. When Entire.io is detected in a repository, Memo automatically reads checkpoint transcripts and fuses the insights into the existing 4 index files:

• stories.json — Each AI session becomes a story (tagged "ai-session")
• arch.json — Structural changes revealed during sessions
• interface.json — New or modified interfaces
• issues.json — Design decisions, TODOs, and bugs discovered

Setup

1. Install Entire CLI:

   # macOS
   brew install entireio/tap/entire
   # or via go install
   go install github.com/entireio/cli/cmd/entire@latest

2. Initialize Entire in your repo:

   entire init

3. Run Memo as usual — it will detect .entire/settings.json and the entire/checkpoints/v1 branch automatically:

   memo watch   # or: memo scan

Entire.io provides a normalized observation layer across multiple AI coding agents (Claude Code, Gemini CLI, OpenCode, etc.), so Memo can index session history regardless of which agent was used.

Output

.memo/
├── index/
│   ├── arch.json       # modules and structure
│   ├── interface.json  # external/internal APIs
│   ├── stories.json    # user stories and flows
│   └── issues.json     # TODOs, decisions, bugs
├── mcp.json            # local MCP config
└── .gitignore          # excludes runtime files

License

MIT