AI-AfterImage — Summary

AI-AfterImage (DragonShadows1978/AI-AfterImage) is an episodic code memory system for AI coding agents. Named after the visual phenomenon where an image persists after you look away, it gives Claude Code persistent memory of code written across sessions. The core mechanism is a single hook file (hooks/afterimage_hook.py) that handles both PreToolUse and PostToolUse events for Write and Edit operations via a deny-then-allow pattern: the first Write/Edit attempt is denied with "You've written similar code before!" context injected, and the retry is allowed after Claude has read the context. Post-write, the code diff is stored in a local SQLite knowledge base for future recall.

22 stars, MIT license, 1 contributor (DragonShadows1978), Python 3.10+. CLI: afterimage. Install: pip install ai-afterimage. Version 0.6.0. Active development through May 2026.

Key features across versions: SQLite KB with hybrid search (v0.1), optional PostgreSQL+pgvector backend (v0.2), semantic chunking with relevance scoring (v0.3), code churn tracking with Gold/Silver/Bronze/Red tier classification (v0.3), Code Intelligence with AST parsing via tree-sitter for 6 languages (v0.5), Codex transcript support (v0.6).

Differs from seeds: closest to memsearch-cc (hook-based episodic memory, Claude Code plugin, deny-on-first-use pattern) but AI-AfterImage is a standalone Python package (not a plugin), focuses exclusively on code files (filters non-code files), adds churn tier warnings and AST-level code intelligence, and supports PostgreSQL+pgvector as an optional backend for concurrent/team use.

AI-AfterImage — Origin and Philosophy

Origin

Author: DragonShadows1978. 22 stars, 3 forks. MIT license. Python 3.10+. 1 contributor. Last pushed 2026-05-10. PyPI: ai-afterimage.

The project description: "Episodic memory for AI coding agents. The ghost of code written, persisting across sessions."

The Problem Statement (verbatim)

"Claude Code starts every session with amnesia. Even though transcripts exist with every Write/Edit ever made, Claude can't remember:

• What code it wrote yesterday
• How it solved a similar problem last week
• Patterns it has used before in this codebase

Users re-explain context. Claude rewrites similar solutions. Institutional knowledge is lost."

Philosophy

AfterImage takes a narrow, code-specific approach to memory: it only cares about Write and Edit events on code files. Markdown, JSON, configs are filtered out. The focus is exclusively on "code written before" — not general conversation history, not project context.

The deny-then-allow pattern is philosophically significant: rather than injecting context as a system prompt addition (which the agent may ignore), AfterImage forces the agent to see the context by denying the first write attempt. The agent must read the "You've written similar code before!" message to retry.

Verbatim Hook Docstring

Provides episodic code memory through Claude Code's hook system:
1. Pre-Write/Edit: DENY first attempt with similar code context (Claude sees this!)
2. Pre-Write/Edit: Check for churn warnings (gold tier, repetitive edits, red tier)
3. Pre-Write/Edit: ALLOW retry attempts (after Claude has seen the context)
4. Post-Write/Edit: Store the code change in KB for future recall
5. Post-Write/Edit: Record edit in churn tracker

The deny-then-allow pattern ensures Claude sees relevant past code BEFORE writing.

Version History Philosophy

• v0.1: Core deny-then-allow hook, SQLite KB, hybrid search
• v0.2: PostgreSQL+pgvector for concurrent/team use — "Start with SQLite. Switch to PostgreSQL if you need concurrent access."
• v0.3: Semantic chunking with explicit relevance scoring formula: Recency 20%, Proximity 25%, Semantic similarity 35%, Project awareness 20%
• v0.3: Churn tracking — "Track file and function modification patterns" to detect premature optimization or unfixed bugs
• v0.5: Code Intelligence — "semantic code understanding, not just text embeddings." AST parsing via tree-sitter for Python, JS/TS, Rust, C, Go
• v0.6: Codex CLI transcript support — session_meta IDs, apply_patch parsing

The Ghost Metaphor

The name "AfterImage" and the description "ghost of code written" frames the tool as passive memory that lingers without requiring active maintenance. The developer doesn't configure what to remember — the hooks automatically record everything and surface relevant patterns when needed.

AI-AfterImage — Architecture

Distribution

Python package on PyPI:

pip install ai-afterimage              # SQLite backend (default)
pip install ai-afterimage[postgresql]  # with PostgreSQL+pgvector support
pip install ai-afterimage[ast]         # with Code Intelligence (tree-sitter)
pip install ai-afterimage[embeddings]  # from source with embeddings

Setup:

afterimage setup   # creates ~/.afterimage/, installs hook, configures settings.json, downloads embedding model

Required Runtime

• Python 3.10+
• Embedding model (~90 MB, downloaded on afterimage setup)
• SQLite (default, built into Python)
• Optional: PostgreSQL + pgvector extension (for concurrent/team access)
• Optional: tree-sitter (for AST parsing in Code Intelligence)

Architecture

Claude Code
      ↓ PreToolUse / PostToolUse (Write, Edit)
hooks/afterimage_hook.py (single file, standalone Python script)
      ├── CodeFilter — is this a code file?
      ├── ChurnTracker — tier classification (Gold/Silver/Bronze/Red)
      ├── HybridSearch — keyword + semantic search
      ├── SemanticChunking — inject_semantic_context()
      └── KnowledgeBase — store/retrieve

Storage:
  SQLite: ~/.afterimage/afterimage.db (default)
  OR PostgreSQL + pgvector (optional, via AFTERIMAGE_PG_PASSWORD env var)

Embedding model: ~90MB local model
Config: ~/.afterimage/config.yaml

Repository Structure

DragonShadows1978/AI-AfterImage/
├── hooks/
│   └── afterimage_hook.py   # single hook file, handles PreToolUse + PostToolUse
├── afterimage/
│   ├── cli.py               # CLI subcommands
│   ├── kb.py                # KnowledgeBase
│   ├── search.py            # HybridSearch
│   ├── filter.py            # CodeFilter (code vs non-code files)
│   ├── embeddings.py        # EmbeddingGenerator
│   ├── churn/               # Code churn tracking + tier classification
│   ├── ast_parser/          # tree-sitter AST parsers
│   ├── language_detection/  # 20+ language detection
│   ├── semantic_chunking/   # Semantic chunking + relevance scoring
│   ├── semantic_index/      # Symbol tables, go-to-definition, call graph
│   ├── storage/
│   │   ├── SQLiteBackend
│   │   └── SyncPostgreSQLBackend
│   ├── extract.py           # Transcript extraction (Claude Code + Codex)
│   ├── inject.py            # Context injection formatting
│   ├── config.py            # Config loading (~/.afterimage/config.yaml)
│   └── migrate.py           # Schema migrations
├── afterimage_embedder/     # Embedding model package
├── docs/
│   ├── semantic_chunking.md
│   └── code_intelligence.md
├── tests/
├── pyproject.toml
└── CHANGELOG.md

Backend Architecture

SQLite (default)

SQLiteBackend at ~/.afterimage/afterimage.db. Zero-config, works out of the box. Brute-force vector search (no native index). Recommended for single-user use up to ~100K entries.

PostgreSQL + pgvector (optional, v0.2.1+)

SyncPostgreSQLBackend with IVFFlat index for native vector search. Required: AFTERIMAGE_PG_PASSWORD env var. Graceful fallback to SQLite if PostgreSQL connection fails. Suitable for concurrent Claude Code sessions or team shared memory.

Priority in hook: returns cached backend → try PostgreSQL → fall back to SQLite.

State Files

• ~/.afterimage/afterimage.db — SQLite knowledge base
• ~/.afterimage/config.yaml — configuration
• ~/.afterimage/.seen_writes — content hashes of write attempts already shown context (deny-then-allow state)
• ~/.claude/hooks/ — hook script installation target
• ~/.claude/settings.json — hook registration

AI-AfterImage — Components

2 Hooks (single file)

Both hooks are handled by hooks/afterimage_hook.py. The same file processes both events:

Hook registration is via ~/.claude/settings.json (installed by afterimage setup).

Deny-Then-Allow Pattern (verbatim logic)

if hook_event == "PreToolUse":
    content_hash = get_content_hash(file_path, content)
    
    if not was_already_shown(content_hash):
        # Collect churn warnings + similar code injections
        if churn_warning or injection:
            mark_as_shown(content_hash)
            output = {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": combined_message
                }
            }
            # Exit 0 — Claude reads the denial reason and retries

    # Was already shown: fall through and allow (exit 0 without output)

was_already_shown tracks content hashes in ~/.afterimage/.seen_writes (last 100 entries). Three key modes for the hash:

• file (default): keyed on file path alone
• content: keyed on file_path + first 500 chars of content
• session_file: keyed on CLAUDE_SESSION_ID + file_path

CLI Commands (afterimage binary)

Churn Tier System

4-tier file classification based on edits in the last 30 days:

Function-level churn: >3 edits to the same function in 24h triggers a "repetitive function edit" warning suggesting root cause investigation.

Code Intelligence (v0.5.0, optional)

Install with pip install ai-afterimage[ast]:

Language Detection (20+ languages):

• Pattern-based with confidence scoring
• Handles polyglot files (HTML+JS+CSS)
• Extensionless scripts (shebang detection)

AST Parsing (tree-sitter):

• Languages: Python, JavaScript, TypeScript, Rust, C, Go
• Incremental parsing for large files
• Extracts: functions, classes, imports, dependencies

Semantic Index:

• Symbol tables with scope-aware resolution
• Go-to-definition across files
• Find all references
• Call graph generation
• Hover information provider
• Basic type inference

Semantic Chunking (v0.3.0)

Relevance scoring formula:

• Recency: 20%
• Proximity (same file/directory): 25%
• Semantic similarity (embedding cosine): 35%
• Project awareness (same project context): 20%

Groups 3+ similar snippets via summarization to reduce token usage. 108x speedup on repeated operations via caching.

Config in ~/.afterimage/config.yaml:

semantic_chunking:
  enabled: true
  max_tokens: 2000
  summarization:
    enabled: true
    summary_mode_threshold: 3

Search: HybridSearch

afterimage/search.py — keyword + semantic search. Runs against backend (SQLite or PostgreSQL). limit=10, threshold=0.01 default. Results ranked by hybrid score.

CodeFilter

afterimage/filter.py — determines if a file is code (not .md, .json, config files). Only code files are stored and searched.

Extract Module (v0.6.0)

afterimage/extract.py — extracts code from Claude Code JSONL transcripts AND Codex transcripts:

• Claude Code: standard JSONL format
• Codex: session_meta session IDs, response_item envelope format (function_call + custom_tool_call), apply_patch unified diff parsing

AI-AfterImage — Uniqueness and Positioning

Differs from Seeds

Closest to memsearch-cc (hook-based episodic memory for Claude Code, deny-on-first-use pattern) but with several key distinctions:

1. Code-only scope: AI-AfterImage filters non-code files via CodeFilter. Only Write/Edit events on code files are stored or searched. memsearch-cc captures all tool interactions regardless of file type. This narrowing reduces noise — the KB only contains patterns relevant to future coding decisions.

2. Single hook file: The entire hook logic lives in hooks/afterimage_hook.py (one file, ~700 lines). memsearch-cc uses 4 separate hook scripts. AfterImage's single-file design makes it auditable and portable without a plugin system.

3. Deny-then-allow with hash tracking: The deny mechanism uses content hash tracking (.seen_writes file) to ensure Claude sees the context exactly once, then proceeds. memsearch-cc injects context as memory context, not a denial. The denial mechanism forces the agent to read the context, not just optionally incorporate it.

4. Churn tier system: Gold/Silver/Bronze/Red classification with function-level tracking (AST-based for Python, regex for others). No other framework in the corpus tracks code modification velocity as a quality signal. "Repetitive function edits" detection surfaces potential bug loops or requirements confusion.

5. Code Intelligence (AST, v0.5): tree-sitter AST parsing for Python, JS/TS, Rust, C, Go. Symbol tables, go-to-definition, find-all-references, call graph. This goes beyond pure text similarity into semantic code understanding.

6. PostgreSQL+pgvector backend: Optional concurrent-access backend. memsearch-cc and agentmemory use local-only storage. AfterImage's PostgreSQL path enables team-shared code memory.

7. Codex transcript support (v0.6): Parses both Claude Code and Codex CLI transcript formats, including apply_patch unified diff parsing. Most memory tools support only their primary host agent.

Positioning

AI-AfterImage is positioned as the minimal, code-focused memory layer. Where agentmemory aims to be comprehensive (53 tools, 12 hooks, 16+ platforms), AfterImage does one thing: remembers code patterns written before and surfaces them at write time via a denial interrupt.

The 22-star count reflects early-stage adoption, not low quality — the code is well-structured with CI badges, codecov integration, and comprehensive tests.

Observable Failure Modes

1. AFTERIMAGE_PATH fallback: The hook searches ~/AI-AfterImage as a default install path. If the package was installed via pip to a different location, the hook fails silently (exits without storing or searching). Diagnosis: afterimage doctor.

2. Content hash collision: The .seen_writes file only stores 100 hashes (last 100 entries). In long sessions with many writes, old hashes cycle out and the hook may re-inject context for the same pattern. The seen_write_key: content mode mitigates this by using content-based hashing.

3. Embedding model absent: If afterimage setup was skipped or the model wasn't downloaded, embeddings are silently omitted — only keyword search runs. The agent gets no warning that semantic search is unavailable.

4. Single-file import complexity: The hook searches SEARCH_PATHS in priority order and loads the afterimage package dynamically. On some system configurations (virtual envs, conda), the import can fail silently and AfterImage operates in a degraded state (no KB access, just exits 0 allowing all writes).

5. Gold tier over-warning: A file with 0–2 edits in 30 days triggers a denial on every write attempt. For new projects or rarely-touched files, this can be noisy — the agent gets warned about "stable files" that simply haven't been written to yet.