dolph-mem

---

English | 中文

---

What is Dolph-Mem?

Dolph-Mem is a file-based memory system for AI coding agents (Claude Code, Codex, etc.). It records observations, searches past work, and maintains project continuity across sessions — without a vector database.

Why "Dolph-Mem"? Dolphins use echolocation to find things in vast oceans. Dolph-Mem does the same for your project history — pinpointing the right context across hundreds of sessions.

Installation

Option 1: Claude Code Plugin (Recommended)

Add dolph-mem as a marketplace source in your Claude Code settings (~/.claude/settings.json):

{
  "extraKnownMarketplaces": {
    "dolph-mem": {
      "source": {
        "source": "github",
        "repo": "oliverhsiung91/dolph-mem"
      }
    }
  },
  "enabledPlugins": {
    "dolph-mem@": true
  }
}

Restart Claude Code — the Setup hook will auto-install memory files into your project.

Option 2: Manual Install

git clone https://github.com/oliverhsiung91/dolph-mem.git
python dolph-mem/tools/install_skill.py --target /path/to/your/repo --agent both

Verify

python /path/to/your/repo/scripts/memory_maintain.py status

Quick Start

Install into your project

python tools/install_skill.py --target /path/to/your/repo --agent both

Check memory state

python /path/to/your/repo/scripts/memory_maintain.py status

Record an observation

python /path/to/your/repo/scripts/memory_maintain.py observe
--type feature
--title "Add streaming parser"

Search past observations

python /path/to/your/repo/scripts/memory_maintain.py search-obs "parser"

## Key Features

| Feature | Description |
|---------|-------------|
| **Structured Observations** | 6 types: feature, bugfix, discovery, decision, change, refactor |
| **3-Layer Search** | Token-efficient: index → timeline → full details |
| **Session Tracking** | Auto-start/end sessions, group observations by work period |
| **Hook Auto-Capture** | Automatically records file changes during sessions |
| **12 MCP Tools** | Full Claude Code integration via MCP server |
| **Cross-Agent** | Works with Claude Code, Codex, and any CLI agent |
| **ChromaDB Opt-In** | Semantic vector search when you need it, keyword search by default |
| **Zero Dependencies** | Core CLI requires only Python standard library |

## Observation Types

| Type | Emoji | Use When |
|------|-------|----------|
| `feature` | 🟣 | New capability added |
| `bugfix` | 🔴 | Bug found and fixed |
| `discovery` | 🔵 | Something learned about the codebase |
| `decision` | ⚖️ | Architectural or design choice made |
| `change` | ✅ | General modification |
| `refactor` | 🔄 | Code restructured without behavior change |

## 3-Layer Search

Token-efficient search that avoids loading irrelevant data:

Layer 1: search-obs "parser" → Compact index with IDs (~50 tokens each) Layer 2: timeline 42 → Context window around an anchor Layer 3: get-obs 42 43 45 → Full details for filtered IDs

## Session Management

```bash
# Start session → all observations get tagged with session_id
python scripts/memory_maintain.py session start --project "my-project"

# End session → writes summary, counts observations
python scripts/memory_maintain.py session end --summary "Completed parser feature"

Cross-Agent Support

Agent	Integration
Claude Code	MCP tools via plugin/mcp_server.py, auto-capture hooks, CLAUDE.md
Codex	Native adaptor via .agents/skills/.../SKILL.md, AGENTS.md
Any agent	Direct CLI: python scripts/memory_maintain.py

Configuration

Variable	Default	Purpose
PROJECT_MEMORY_ROOT	Current directory	Root of the project repo
PROJECT_MEMORY_USE_CHROMADB	disabled	Set 1 to enable semantic search

Repository Layout