Introduction
# GitNotesMemory - Claude Integration Guide
## CRITICAL: SILENT OPERATION RULES
**These rules are ABSOLUTE and must NEVER be violated:**
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