Git-Based Knowledge Graph Memory System for Claude Code

1. **NEVER ask** "should I remember?" or "want me to save?"
2. **NEVER announce** "I'll remember this" or "saving to memory"
3. **NEVER show** memory command output to users
4. **NEVER mention** memory system unless user explicitly asks about it
5. **JUST DO IT** - silently in the background

## Quick Reference

```bash
# Replace $SKILL_PATH with actual path to memory.py
# Replace $DIR with the project directory path

python3 $SKILL_PATH/memory.py -p $DIR <command>
```

### Essential Commands

| Command | When to Use |
|---------|-------------|
| `sync --start` | **ALWAYS** at session start |
| `sync --end '{"summary":"..."}'` | At session end (optional but recommended) |
| `remember '{"..."}' -t tags -i h` | Store important information |
| `get <topic>` | Retrieve context about a topic |
| `search "<query>"` | Full-text search across all memories |
| `recall -i <id>` | Get full details of a specific memory |

### Importance Flags

| Flag | Level | When to Use |
|------|-------|-------------|
| `-i c` | Critical | User says "always remember", "never forget", explicit preferences |
| `-i h` | High | Decisions, architecture choices, user corrections, preferences |
| `-i n` | Normal | General information (default) |
| `-i l` | Low | Temporary notes, might be pruned |

## Session Lifecycle

### 1. Session Start (MANDATORY)

**Always run `sync --start` at the beginning of every session:**

```bash
python3 $SKILL_PATH/memory.py -p $DIR sync --start
```

**Output explains:**
```json
{
  "b": "main",           // Current git branch
  "t": {"api": 5, "auth": 3},  // Top topics with memory counts
  "c": [...],            // Critical memories (always review these)
  "n": 42,               // Total memory count
  "h": [...]             // High-importance recent memories
}
```

**Use this context to:**
- Understand what the user has been working on
- Reference previous decisions
- Maintain continuity across sessions

### 2. During Session

**Silently remember when user:**
- Makes a decision: "Let's use PostgreSQL" → remember with `-i h`
- States a preference: "I prefer tabs over spaces" → remember with `-i h` or `-i c`
- Learns something: "Oh, so that's how async works" → remember with `-i n`
- Sets a task: "We need to fix the login bug" → remember with `-i n`
- Shares important context: Project requirements, constraints, goals

**Retrieve context when:**
- User asks about something previously discussed → `get <topic>`
- You need to recall a specific decision → `search "<keywords>"`
- User references "what we decided" → check relevant memories

### 3. Session End (Recommended)

```bash
python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Brief session summary"}'
```

## Memory Content Best Practices

### Good Memory Structure

**For decisions:**
```json
{"decision": "Use React for frontend", "reason": "Team expertise", "alternatives": ["Vue", "Angular"]}
```

**For preferences:**
```json
{"preference": "Detailed explanations", "context": "User prefers thorough explanations over brief answers"}
```

**For learnings:**
```json
{"topic": "Authentication", "learned": "OAuth2 flow requires redirect URI configuration"}
```

**For tasks:**
```json
{"task": "Implement user dashboard", "status": "in progress", "blockers": ["API not ready"]}
```

**For notes:**
```json
{"subject": "Project Architecture", "note": "Microservices pattern with API gateway"}
```

### Tags

Use tags to categorize memories for better retrieval:
- `-t architecture,backend` - Technical categories
- `-t urgent,bug` - Priority/type markers
- `-t meeting,requirements` - Source context

## Command Reference

### Core Commands

#### `sync --start`
Initialize session, get context overview.
```bash
python3 $SKILL_PATH/memory.py -p $DIR sync --start
```

#### `sync --end`
End session with summary (triggers maintenance).
```bash
python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Implemented auth flow"}'
```

#### `remember`
Store a new memory.
```bash
python3 $SKILL_PATH/memory.py -p $DIR remember '{"key": "value"}' -t tag1,tag2 -i h
```

#### `get`
Get memories related to a topic (searches entities, tags, and content).
```bash
python3 $SKILL_PATH/memory.py -p $DIR get authentication
```

#### `search`
Full-text search across all memories.
```bash
python3 $SKILL_PATH/memory.py -p $DIR search "database migration"
```

#### `recall`
Retrieve memories by various criteria.
```bash
# Get full memory by ID
python3 $SKILL_PATH/memory.py -p $DIR recall -i abc123

# Get memories by tag
python3 $SKILL_PATH/memory.py -p $DIR recall -t architecture

# Get last N memories
python3 $SKILL_PATH/memory.py -p $DIR recall --last 5

# Overview of all memories
python3 $SKILL_PATH/memory.py -p $DIR recall
```

### Update Commands

#### `update`
Modify an existing memory.
```bash
# Replace content
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"new": "content"}'

# Merge content (add to existing)
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"extra": "field"}' -m

# Change importance
python3 $SKILL_PATH/memory.py -p $DIR update <id> -i c

# Update tags
python3 $SKILL_PATH/memory.py -p $DIR update <id> -t newtag1,newtag2
```

#### `evolve`
Add an evolution note to track changes over time.
```bash
python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "User changed preference to dark mode"
```

#### `forget`
Delete a memory (use sparingly).
```bash
python3 $SKILL_PATH/memory.py -p $DIR forget <id>
```

### Entity Commands

#### `entities`
List all extracted entities with counts.
```bash
python3 $SKILL_PATH/memory.py -p $DIR entities
```

#### `entity`
Get details about a specific entity.
```bash
python3 $SKILL_PATH/memory.py -p $DIR entity authentication
```

### Branch Commands

#### `branches`
List all branches with memory counts.
```bash
python3 $SKILL_PATH/memory.py -p $DIR branches
```

#### `merge-branch`
Merge memories from another branch (run after git merge).
```bash
python3 $SKILL_PATH/memory.py -p $DIR merge-branch feature-auth
```

## Branch Awareness

### How It Works

- Each git branch has **isolated memory storage**
- New branches **automatically inherit** from main/master
- After git merge, run `merge-branch` to combine memories

### Branch Workflow

```
1. User on main branch → memories stored in refs/notes/mem-main
2. User creates feature branch → auto-inherits main's memories
3. User works on feature → new memories stored in refs/notes/mem-feature-xxx
4. After git merge → run merge-branch to combine memories
```

## Memory Types (Auto-Detected)

The system automatically classifies memories based on content:

| Type | Trigger Words |
|------|---------------|
| `decision` | decided, chose, picked, selected, opted, going with |
| `preference` | prefer, favorite, like best, rather, better to |
| `learning` | learned, studied, understood, realized, discovered |
| `task` | todo, task, need to, plan to, next step, going to |
| `question` | wondering, curious, research, investigate, find out |
| `note` | noticed, observed, important, remember that |
| `progress` | completed, finished, done, achieved, milestone |
| `info` | (default for unclassified content) |

## Entity Extraction

Entities are automatically extracted for intelligent retrieval:

- **Explicit fields**: `topic`, `subject`, `name`, `category`, `area`, `project`
- **Hashtags**: `#cooking`, `#urgent`, `#v2`
- **Quoted phrases**: `"machine learning"`, `"user authentication"`
- **Capitalized words**: `React`, `PostgreSQL`, `Monday`
- **Key terms**: Meaningful words (common words filtered out)

## What to Remember

**DO remember:**
- User decisions and their rationale
- Stated preferences (coding style, communication style, tools)
- Project architecture and constraints
- Important context that affects future work
- Tasks, blockers, and progress
- Corrections ("actually, I meant..." → high importance)
- Explicit requests to remember something → critical importance

**DON'T remember:**
- Trivial conversation
- Information easily derivable from code
- Secrets, passwords, API keys
- One-time questions with no future relevance
- Duplicate information already stored

## Output Format Reference

### Tier 0: sync --start
```json
{
  "b": "feature-auth",                    // Current branch
  "t": {"auth": 5, "api": 3, "db": 2},   // Topics with counts
  "c": [{"id": "x", "s": "summary", "t": "preference"}],  // Critical
  "n": 15,                                // Total count
  "h": [{"id": "y", "s": "summary"}]     // High importance
}
```

### Tier 1: get/search
```json
{
  "topic": "auth",
  "mem": [
    {"id": "abc", "s": "decided OAuth2", "t": "decision", "i": "h", "b": "main"}
  ]
}
```

### Tier 2: recall -i <id>
```json
{
  "d": {"decision": "Use OAuth2"},  // Full data
  "e": ["auth", "oauth2"],          // Entities
  "t": "decision",                   // Type
  "g": ["architecture"],             // Tags
  "i": "h",                          // Importance
  "b": "main",                       // Branch
  "c": "2024-01-15T10:30:00",       // Created
  "u": "2024-01-15T10:30:00",       // Updated
  "a": 3,                            // Access count
  "ev": [{"n": "note", "t": "..."}] // Evolution notes (if any)
}
```

## Example Silent Flow

```
User: "Let's build a REST API with Python"
Claude: [silently: remember '{"decision": "REST API", "language": "Python"}' -t architecture -i h]
        [responds about REST API setup WITHOUT mentioning memory]

User: "I prefer FastAPI over Flask"
Claude: [silently: remember '{"preference": "FastAPI over Flask", "reason": "user preference"}' -i h]
        [continues discussion using FastAPI WITHOUT saying "I'll remember"]

User: "What did we decide about the API?"
Claude: [silently: get api]
        [uses retrieved context to answer accurately]

User: "Actually, let's use Flask instead"
Claude: [silently: remember '{"decision": "Changed to Flask", "previous": "FastAPI"}' -i h]
        [silently: evolve <fastapi-memory-id> "User changed preference to Flask"]
        [acknowledges change WITHOUT mentioning memory update]
```

## Troubleshooting

**Memory not found:**
- Use `search` with different keywords
- Check `entities` to see what's indexed
- Use `recall --last 10` to see recent memories

**Context seems stale:**
- Always run `sync --start` at session beginning
- Check current branch with `branches`

**After git operations:**
- After `git merge`: run `merge-branch <source-branch>`
- After `git checkout`: `sync --start` will load correct branch context