🧠 git-memory

Persistent project memory for AI agents.

git-memory indexes your git history, extracts features and decisions, maps source files, and builds a searchable knowledge graph — so your AI never loses context, redoes work, or makes the same mistake twice.

$ git-memory init
✅ git-memory initialized for 'my-project'

$ git-memory sync
📥 my-project: 342 new commits (of 342 scanned)
📂 47 files mapped, 28 feature links
✅ Sync: 342 new commits, 89 new features (89 total)

$ git-memory query "authentication"
🔍 Results for 'authentication' (6 matches):

  [100%] ⭐ FEATURE: JWT auth middleware with refresh tokens [active]
       Commit: a3f2c91 | Date: 2026-01-15

  [ 87%] 🏛️  DECISION (2026-01-12, high)
       Use JWT over session cookies for stateless API auth

  [ 72%] 📂 FILE: auth_middleware.py
       JWT authentication and authorization middleware

Why?

AI agents start every session with amnesia. They don't know:

• What features already exist in your project
• What architectural decisions were made and why
• Which files handle what functionality
• What mistakes were made before (and shouldn't be repeated)

git-memory fixes this. One command gives your AI instant recall of your entire project history.

Features

🔍 Semantic Search — BM25 scoring with synonym expansion. Ask in natural language, get relevant commits, features, decisions, and files.

⭐ Auto Feature Extraction — feat: conventional commits are automatically extracted as searchable features with dates and linked files.

🏛️ Decision Records — Record architectural decisions with importance levels. Never re-debate the same choice.

🚫 Anti-Pattern Tracking — Document mistakes with prevention rules and severity. The AI gets warned before repeating them.

📂 File Purpose Mapping — Source files are scanned and their purposes inferred from docstrings and comments. file-for "parsing" instantly shows relevant files.

🔗 Cross-References — Features auto-linked to files via git commit change lists. See which features touch which files.

📦 Multi-Project — Index additional repos alongside your main project. Shared libraries, monorepo support.

⚡ Zero Dependencies — Pure Python 3.8+ and SQLite. No pip install. No API keys. No network. Works offline.

Installation

Option 1: Direct download (recommended)

curl -o /usr/local/bin/git-memory \
  https://raw.githubusercontent.com/bandtincorporated8/git-memory/main/git-memory
chmod +x /usr/local/bin/git-memory

Option 2: Clone and symlink

git clone https://github.com/bandtincorporated8/git-memory.git
ln -s $(pwd)/git-memory/git-memory /usr/local/bin/git-memory

Option 3: OpenClaw Skill

# Drop the skill into your OpenClaw workspace:
cp -r skill/ ~/.openclaw/workspace/skills/git-memory

Quick Start

# 1. Initialize in any git repo
cd my-project
git-memory init

# 2. Import your history
git-memory sync

# 3. Search everything
git-memory query "what does the parser do"

# 4. Find files by topic
git-memory file-for "database"

# 5. Record a decision
git-memory add-decision "Use PostgreSQL for production" --importance high

# 6. Record an anti-pattern
git-memory add-anti "Never use rm -rf on data dirs" \
  --rule "Always use trash or backup first" \
  --severity critical

Commands

Command	Description
git-memory init	Initialize memory for current git repo
git-memory sync	Import commits, extract features, map files
git-memory sync --if-stale	Only sync if >1h since last sync
git-memory sync --force	Full rebuild (re-scan all files)
git-memory query <text>	Semantic search across all knowledge
git-memory features	List extracted features
git-memory features --status active	Filter by status
git-memory decisions	List recorded decisions
git-memory anti-patterns	List anti-patterns
git-memory files	List source files with purposes
git-memory file-for <text>	Find files related to a topic
git-memory add-decision <text>	Record a decision
git-memory add-anti <text>	Record an anti-pattern
git-memory status	DB stats and health
git-memory projects	List all git-memory projects

How It Works

Architecture

your-project/
├── .git/                    # Your existing git history
├── .git-memory/             # ← Created by git-memory (gitignored)
│   ├── memory.db            # SQLite knowledge graph
│   └── config.json          # Project-specific settings
├── src/
│   └── ...your code...

Knowledge Pipeline

Git Log ──→ Commit Import ──→ Feature Extraction ──→ File Mapping
                                     │                     │
                                     ▼                     ▼
                              features table          files table
                                     │                     │
                                     └──── Cross-Refs ─────┘
                                              │
                            Decisions ──→ BM25 Index ←── Anti-Patterns
                                              │
                                        Semantic Search

1. Commit Import: All git commits imported with file stats, categorized by conventional commit prefix (feat:, fix:, etc.)
2. Feature Extraction: feat: commits automatically create searchable feature records
3. File Mapping: Source files scanned, purposes inferred from docstrings/comments
4. Cross-References: Features linked to files via commit change lists
5. BM25 Search: Full-text index with synonym expansion for natural language queries

Search Engine

git-memory uses BM25 (Okapi) ranking with:

• Synonym expansion: "notification" also matches "alert", "popup", "toast"
• Substring boosting: Exact phrase matches rank higher
• Multi-token bonus: All query terms present in a document = extra score
• Configurable: Add domain-specific synonyms in config.json

Configuration

Per-project settings at .git-memory/config.json:

{
  "file_extensions": [".py", ".js", ".ts"],
  "src_dirs": ["src", "lib", "app"],
  "synonyms": {
    "trade": ["signal", "position", "order", "fill"],
    "auth": ["login", "jwt", "token", "session", "oauth"]
  },
  "extra_repos": [
    { "path": "~/shared-lib", "name": "shared-lib" }
  ]
}

Key	Description	Default
file_extensions	Source file types to scan	Auto-detected
src_dirs	Directories to scan for source files	["src", "lib", "app"]
synonyms	Domain-specific search term expansion	{}
extra_repos	Additional repos to index together	[]

For AI Agents (OpenClaw Skill)

git-memory ships as an OpenClaw skill. When installed, it:

1. Auto-activates when the agent enters a git-tracked directory
2. Syncs on session start (sync --if-stale — skips if fresh)
3. Queries before building to check if features already exist
4. Records decisions the agent makes during development
5. Warns about anti-patterns before the agent repeats mistakes

Integration with state-loader

# In your state-loader or session-start script:
if command -v git-memory &>/dev/null && [ -d ".git-memory" ]; then
    git-memory sync --if-stale --quiet
fi

Systemd Timer (always-fresh memory)

# Sync every 4 hours, even between agent sessions:
cat > ~/.config/systemd/user/git-memory-sync.service << 'EOF'
[Unit]
Description=git-memory sync
[Service]
Type=oneshot
WorkingDirectory=/path/to/your/project
ExecStart=git-memory sync
TimeoutStartSec=120
EOF

cat > ~/.config/systemd/user/git-memory-sync.timer << 'EOF'
[Unit]
Description=git-memory sync timer
[Timer]
OnBootSec=5min
OnUnitActiveSec=4h
Persistent=true
[Install]
WantedBy=timers.target
EOF

systemctl --user enable --now git-memory-sync.timer

Database Schema

Click to expand schema

commits

Column	Type	Description
hash	TEXT PK	Full SHA
short_hash	TEXT	7-char hash
message	TEXT	Commit message
category	TEXT	feat/fix/docs/refactor/chore/other
date	TEXT	ISO 8601
author	TEXT	Author name
repo	TEXT	Repository name
files_changed	TEXT	JSON array of paths
insertions	INT	Lines added
deletions	INT	Lines removed

features

Column	Type	Description
id	INT PK	Auto-increment
name	TEXT UNIQUE	Feature name
description	TEXT	Full commit message
commit_hash	TEXT	Reference hash
file_paths	TEXT	JSON array
status	TEXT	active/deprecated/planned
implemented_date	TEXT	YYYY-MM-DD

decisions

Column	Type	Description
id	INT PK	Auto-increment
date	TEXT	YYYY-MM-DD
decision	TEXT	What was decided
context	TEXT	Why
category	TEXT	general/architecture/policy
importance	TEXT	normal/high/critical

anti_patterns

Column	Type	Description
id	INT PK	Auto-increment
description	TEXT	What went wrong
incident_date	TEXT	When
prevention_rule	TEXT	How to prevent
severity	TEXT	low/medium/high/critical

files

Column	Type	Description
id	INT PK	Auto-increment
path	TEXT UNIQUE	File path
purpose	TEXT	Inferred purpose
repo	TEXT	Repository name
related_features	TEXT	JSON feature names

Performance

Project Size	Commits	Sync Time	DB Size	Features
Small (50 commits)	54	~2s	140 KB	34
Medium (500 commits)	~500	~4s	~1 MB	~150
Large (9,000+ commits)	9,186	~8s	~3 MB	1,140

Requirements

• Python 3.8+
• Git
• That's it. No pip install. No API keys. No internet.

Contributing

PRs welcome. Keep it zero-dependency.

License

MIT — see LICENSE.

---

Built by OinkX 🐷 — the 31337 Space Pig.