knowhook 0.1.5

Compaction-resistant context layer for AI coding agents

knowhook

Compaction-resistant context layer for AI coding agents.

When you use Claude Code (or any AI agent) in long sessions, auto-compaction summarizes and drops older messages to free up the context window. After compaction, the agent forgets architectural decisions, file dependencies, rejected approaches, and what work is done vs pending.

knowhook fixes this. It hooks into Claude Code's lifecycle to snapshot context before compaction and inject it back after — so Claude picks up exactly where it left off.

Install

pip install knowhook

Setup (2 commands)

know init                  # Create .context.yaml in your project
know claude install        # Install Claude Code hooks + teach Claude about know

That's it. Everything else is automatic.

What happens automatically

After know claude install, three hooks run in the background:

Hook	Trigger	What it does
PostToolUse	Every file Edit/Write	Tracks which files Claude touched
PreCompact	Before compaction	Snapshots all context to .know/snapshots/
SessionStart	After compaction	Injects ~500 token context briefing back into Claude

Claude also gets a rules file (.claude/rules/know-context.md) that it re-reads every turn — this survives compaction by design.

Commands

Core workflow

know decide "Using JWT not sessions" -r "Stateless for API gateway"   # Log a decision
know map                    # Generate dependency map of your project
know snapshot               # Manually create a context snapshot
know restore                # Print latest snapshot (pipe-friendly)
know sync                   # Regenerate .claude/rules/know-context.md

Project setup

know init [DIRECTORY]       # Create .context.yaml
know show                   # Display current config
know edit                   # Edit .context.yaml interactively
know update                 # Quick-edit task, goals, rules from CLI

Claude Code integration

know claude install         # Install hooks + usage rules
know claude uninstall       # Remove hooks + usage rules

Interactive TUI

know                        # Launch interactive dashboard (no arguments)

Slash commands inside the TUI: /snapshot, /restore, /decide, /map, /sync, /init, /show, /edit, /update, /help, /quit

How it works

  DURING SESSION
  Claude edits files --> PostToolUse hook --> know tracks touched files
  User runs `know decide` --> logs decision to .know/decisions.json

  BEFORE COMPACTION
  Auto-compaction triggers --> PreCompact hook --> know snapshot
    Saves: task, goals, decisions, files touched, dependency edges

  AFTER COMPACTION
  SessionStart hook --> know restore --> injects context briefing into Claude
    Claude sees: structured ~500 token briefing with everything it needs

  ALWAYS LOADED
  .claude/rules/know-context.md --> auto-generated rules file
    Contains: current task, decisions, rules, key files
    Survives compaction because Claude re-reads rules from disk

What Claude gets after compaction

=== KNOW: Post-Compaction Context Recovery ===
PROJECT: my-project
CURRENT TASK [42]: Implement JWT auth (status: active)
GOALS: Stateless API auth, Token refresh endpoint

DECISIONS:
- [D1] Using JWT not sessions — stateless for API gateway
- [D2] Refresh tokens in Redis — fast TTL expiry

RULES:
- No print statements
- All endpoints require auth middleware

FILES TOUCHED THIS SESSION:
- auth.py (edit), db.py (edit), models.py (write)

DEPENDENCIES:
- auth.py -> db.py (imports UserModel)
- routes/api.py -> auth.py (imports require_auth)

COMPLETED: Set up JWT signing, Created User model
PENDING: Refresh token endpoint, Token revocation
REJECTED: Session-based auth (horizontal scaling issues)
=== END KNOW CONTEXT ===

.context.yaml schema

project_name: my-project
goals:
  - Define project goals
current_task:
  id: "1"
  description: Initial setup
  status: active        # active | skipped | completed
tech_stack:
  - python
  - fastapi
rules:
  - No print statements in production code

Data layout

.know/                          # Project-local, created automatically
  snapshots/                    # Timestamped JSON snapshots
  decisions.json                # Architectural decisions log
  map.json                      # Dependency map cache
  session.json                  # Current session file tracker

.claude/
  rules/know-context.md         # Auto-generated, always loaded by Claude
  rules/know-usage.md           # Teaches Claude about know commands
  settings.local.json           # Hook configuration

Who benefits most

• Long sessions (1hr+) — multiple compactions, high context loss risk
• Multi-file refactors — touching 10+ files, easy to forget earlier changes
• Architecture-heavy work — decisions that must stay consistent
• Multi-day projects — know restore brings yesterday's context back

Requirements

• Python 3.10+
• Claude Code (for hooks integration)

License

MIT