https://github.com/sunset331/ai-hooks
Persistent project memory for AI coding. SQLite events, git hooks, Claude Code integration.
https://github.com/sunset331/ai-hooks
ai-coding claude claude-code developer-tools git-hooks project-memory sqlite
Last synced: about 5 hours ago
JSON representation
Persistent project memory for AI coding. SQLite events, git hooks, Claude Code integration.
- Host: GitHub
- URL: https://github.com/sunset331/ai-hooks
- Owner: sunset331
- License: mit
- Created: 2026-07-01T07:07:10.000Z (1 day ago)
- Default Branch: master
- Last Pushed: 2026-07-01T07:28:10.000Z (1 day ago)
- Last Synced: 2026-07-01T09:20:38.978Z (1 day ago)
- Topics: ai-coding, claude, claude-code, developer-tools, git-hooks, project-memory, sqlite
- Language: Shell
- Homepage:
- Size: 39.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ai-hooks — Persistent Project Memory for AI Coding
```text
AI loses memory between sessions.
This project fixes that.
```
Close Claude Code. All context gone. Switch projects. Re-read everything. Pick up a repo after a week. Start from zero.
**ai-hooks gives Claude Code persistent project memory.** It records every commit, checkout, and AI action as events in SQLite, auto-injects them when you start a session, and keeps STATUS.md always current.
No cloud. No API. No vendor lock-in. Just a Bash script, a Python SQLite wrapper, and git hooks.
```text
git commit
│
▼
SQLite Events ──→ Project State ──→ Claude Session (auto-injected on start)
→ STATUS.md (auto-rendered)
```
## Quick Start
```bash
# 1. One command to install
git clone https://github.com/sunset331/ai-hooks.git
cd ai-hooks && bash install.sh
# 2. One command to add to any project
ai-init ~/my-project
# 3. Work normally. That's it.
git commit -m "fix: login bug" # → event + state auto-recorded
git checkout feature-branch # → state summary printed
# next Claude Code session → context auto-injected
```
| Situation | Without ai-hooks | With ai-hooks |
|-----------|-----------------|---------------|
| Close Claude Code | Lose all context | Auto-injected next session |
| Switch projects | Re-read everything | Smart Resume picks up where you left off |
| STATUS.md outdated | Drift, stale | Auto-rendered every commit |
| State corrupted | Manual recovery | `doctor --repair` auto-rebuilds from events |
| `__pycache__` in commit | Caught at PR review | Warning at commit time |
| New AI tool joins | Starts from zero | Reads same `.ai/` files |
## Architecture
```
.ai/ # Per-project (created by ai-init)
├── project.db # SQLite — events + state
├── STATUS.md # Auto-rendered (read-only)
├── MEMORY.md # You write: bugs, fixes, milestones
├── DECISIONS.md # You write: architecture rationale
├── CHECKLIST.md # Review checklist
└── WORKFLOW.md # Project workflow
.claude/
├── settings.json # SessionStart hook for context injection
└── skills/ai-review/SKILL.md # /ai-review command
Data flow:
git commit → post-commit hook
→ record_event.py → SQLite events (append-only)
→ update_state.py → SQLite state (KV, upsert)
→ render_state.py → STATUS.md (overwrite)
next Claude start → SessionStart hook → db.py summary → context
daily → Task Scheduler → scheduler-check.ps1 → health check (read-only)
```
## Commands
| Command | Description |
|---------|-------------|
| `ai-init ` | Initialize `.ai/` system in a project (idempotent) |
| `ai-doctor ` | Diagnose `.ai/` health |
| `ai-update ` | Upgrade hooks path + DB schema |
| `ai-uninstall ` | Remove hook config (keeps `.ai/` data) |
## Events
Every state change is an append-only event. No data loss, full audit trail.
| Type | Trigger | Payload |
|------|---------|---------|
| `commit` | post-commit hook | `{sha, message, date, author}` |
| `checkout` | post-checkout hook | `{branch, from}` |
| `ai_session` | Claude Code | `{action, model, summary}` |
| `scheduler_check` | Task Scheduler | `{status, dirty_count, warnings}` |
```bash
sqlite3 .ai/project.db "SELECT id, type, payload FROM events"
```
## Who Is This For
- **You use Claude Code daily** and hate losing context between sessions
- **You juggle multiple projects** and need instant state recovery
- **You want your AI memory to outlive any specific tool**
- **You care about engineering fundamentals** — events, state, SQLite — not prompt hacks
## Requirements
- Bash 4+
- Python 3.8+ (with sqlite3)
- Git (optional: hooks need it, `.ai/` files work without)
## Supported AI Tools
- **Claude Code** — Full support (hooks, sessions, skill)
- **Any AI** — `.ai/` is plain Markdown + SQLite, zero dependency on any provider
## License
MIT
---
*[中文使用手册](https://github.com/sunset331/ai-hooks/blob/master/docs/usage-zh.md)* — 完整的中文文档