Git-Based Knowledge Graph Memory System for Claude Code

Git-Notes-Based knowledge graph memory system. Claude should use this SILENTLY and AUTOMATICALLY - never ask users about memory operations. Branch-aware persistent memory using git notes. Handles context, decisions, tasks, and learnings across sessions.

Security Scan

The skill's behavior (silent, automatic memory collection written into git notes and automatic repo changes) is coherent with its description but raises privacy and surprise-modification concerns and some metadata/instruction inconsistencies.

Purpose & Capability

The code and documentation match the stated purpose: a git-notes-based, branch-aware memory system. However the registry metadata claims no required binaries or environment yet the SKILL.md and memory.py rely on Python and the git CLI. The mismatch between declared requirements and actual runtime needs (git, python) is inconsistent and should be corrected.

Instruction Scope

SKILL.md explicitly instructs the agent to operate SILENTLY and AUTOMATICALLY (never ask, never announce, never show output). The skill runs git operations that can create an initial commit, set git config, write refs/notes, and read/infer context from the repository—actions that modify local project state and persist potentially sensitive content. The silent, always-run guidance increases risk because users may not be aware data is being collected or stored.

Install Mechanism

There is no install spec and no external downloads (good). The package includes local code files (memory.py, README, SKILL.md) which will be copied into the agent's skills dir per README. That is lower risk than remote downloads, but the presence of executable code means it will run arbitrary local git commands when invoked.

Credentials

The skill requests no credentials or env vars, which is appropriate on its face. However it will access and modify the repository (.git), create commits, and write git notes that can contain user content. Those capabilities are powerful relative to 'simple memory' — storing decisions, preferences, tasks and other possibly sensitive content in local git metadata could be leaked if the repo is pushed. The metadata omission of 'requires git' and 'requires python' is also misleading.

Persistence & Privilege

The skill intentionally creates persistent data inside the project's git notes (refs/notes/*), can auto-initialize a git repo and create an initial commit, and adjusts local git config. Although 'always' is false, the README and SKILL.md push for making the skill always active (example CLAUDE.md: 'YOU MUST ALWAYS USE git-notes-memory SKILL'), and the SILENT rules promote unobtrusive, persistent behavior. These factors increase the blast radius of mistakes or misuse.

What to consider before installing

This skill will silently read project content and persist 'memories' into the repository's git notes and may create an initial commit and local git config if none exist. Before installing: 1) Review memory.py in full to confirm what content it records; 2) Don't enable it on repositories containing secrets or that you might push to a remote (memories could be pushed accidentally); 3) Prefer an isolated test repo first; 4) Require explicit, visible user consent rather than the skill's 'never tell the user' policy; and 5) Fix the metadata to list git and python as required binaries so you (or an admin) know what will run.

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

# 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:

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

Output explains:

{
  "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)

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

Memory Content Best Practices

Good Memory Structure

For decisions:

{"decision": "Use React for frontend", "reason": "Team expertise", "alternatives": ["Vue", "Angular"]}

For preferences:

{"preference": "Detailed explanations", "context": "User prefers thorough explanations over brief answers"}

For learnings:

{"topic": "Authentication", "learned": "OAuth2 flow requires redirect URI configuration"}

For tasks:

{"task": "Implement user dashboard", "status": "in progress", "blockers": ["API not ready"]}

For notes:

{"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.

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

sync --end

End session with summary (triggers maintenance).

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Implemented auth flow"}'

remember

Store a new memory.

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).

python3 $SKILL_PATH/memory.py -p $DIR get authentication

search

Full-text search across all memories.

python3 $SKILL_PATH/memory.py -p $DIR search "database migration"

recall

Retrieve memories by various criteria.

# 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.

# 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.

python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "User changed preference to dark mode"

forget

Delete a memory (use sparingly).

python3 $SKILL_PATH/memory.py -p $DIR forget <id>

Entity Commands

entities

List all extracted entities with counts.

python3 $SKILL_PATH/memory.py -p $DIR entities

entity

Get details about a specific entity.

python3 $SKILL_PATH/memory.py -p $DIR entity authentication

Branch Commands

branches

List all branches with memory counts.

python3 $SKILL_PATH/memory.py -p $DIR branches

merge-branch

Merge memories from another branch (run after git merge).

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

{
  "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

{
  "topic": "auth",
  "mem": [
    {"id": "abc", "s": "decided OAuth2", "t": "decision", "i": "h", "b": "main"}
  ]
}

Tier 2: recall -i <id>

{
  "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