knowhook 0.1.5
Compaction-resistant context layer for AI coding agents
Requires Python: >=3.10
Keywords: ai, context, claude, compaction, coding-agent

# 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

```bash
pip install knowhook
```

## Setup (2 commands)

```bash
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

```bash
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

```bash
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

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

### Interactive TUI

```bash
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

```yaml
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