Checkpin

Let AI Agents have persistent, self-organizing memory.

Checkpin is an agent-native state management tool that solves core pain points of AI agents like Claude Code:

• No continuity between sessions
• Previously learned context is completely lost
• State pollution between different tasks
• Notes accumulate but no one organizes them

Features

🔄 Automatic Session Continuity

• Pre-session: Automatically loads relevant context when a session starts
• Post-session: Automatically extracts and saves learnings when a session ends

🎯 Smart Task Detection (Phase 2)

• Detects if user is continuing a previous task or starting a new one
• Isolates state between different tasks

🧹 Self-Organizing (Phase 3)

• Agent can organize its own notes
• Merge duplicates, summarize details, prune outdated, establish links

📊 Hierarchical Storage

Global (user preferences, across all projects)
  └── Project (project context, across all tasks in the project)
        └── Task (specific task state)

📚 Three-Layer Knowledge Structure

Checkpoint (raw session data)
  → Notes (organized, structured knowledge)
    → Principles (extracted core principles)

Installation

npm install -g checkpin

Or in your project:

npm install checkpin

Quick Start

1. Initialize in your project

cd your-project
checkpin state:init

This creates .agent-state/ directory:

.agent-state/
├── project.json        # Project context
├── sessions/           # Raw session data
├── tasks/              # Task states
└── checkpoints/        # Saved checkpoints

2. Configure Claude Code Hooks

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "PreSessionStart": [
      {
        "matcher": "*",
        "command": "npx checkpin hook:pre-session"
      }
    ],
    "PostSessionStop": [
      {
        "matcher": "*",
        "command": "npx checkpin hook:post-session"
      }
    ]
  }
}

3. Use CLI Commands

# Checkpoints
checkpin checkpoint:save "Before refactoring auth"
checkpin checkpoint:list
checkpin checkpoint:load cp-abc123

# Tasks
checkpin task:list
checkpin task:new auth-refactor "Refactoring authentication system"
checkpin task:end
checkpin task:switch task-xyz789

# Notes
checkpin notes:show                # Show project notes
checkpin notes:show task           # Show current task notes
checkpin notes:add "User prefers functional style"
checkpin notes:search "auth"
checkpin notes:organize            # Clean up notes

# State
checkpin state:show               # Show overview
checkpin state:init               # Initialize

4. Use the Skill (in Claude Code)

If you've installed the checkpin skill, you can use it directly:

/checkpin save Before refactoring auth
/checkpin task new auth-refactor Refactoring authentication
/checkpin notes
/checkpin status

How It Works

Pre-Session Hook

When a session starts, checkpin:

1. Loads global preferences and principles
2. Loads project context and notes
3. Loads active task state
4. Retrieves recent session learnings
5. Injects all relevant context into the session

The injected context looks like:

<agent-memory>
## Context
Communication style: concise, technical
Project: E-commerce platform

## Core Principles
- Always use TypeScript for new code
- Prefer functional programming patterns

## Relevant Notes
- User prefers dark mode implementation
- Auth tokens stored in httpOnly cookies
- [Recent] Decided to use Redis for caching

## Active Todos
- 🔄 Implement refresh token rotation
- ⏳ Add rate limiting to auth endpoints
</agent-memory>

Post-Session Hook

When a session ends, checkpin:

1. Parses the session transcript
2. Extracts learnings using keyword detection:
   • Decisions: "decided", "chose", "going with"
   • Learnings: "learned", "discovered", "turns out"
   • Preferences: "prefer", "always", "style"
   • Todos: "need to", "should", "remember to"
3. Saves session data and extracted insights
4. Updates project/task state

Storage Structure

~/.agent-state/
└── global.json              # Global user preferences

your-project/.agent-state/
├── project.json             # Project-level context
├── sessions/
│   ├── 2025-01-23-abc123.json
│   └── 2025-01-23-def456.json
├── tasks/
│   ├── task-abc123.json
│   └── task-def456.json
└── checkpoints/
    ├── cp-abc123.json
    └── cp-def456.json

API Usage

import { Storage, extractFromSession } from 'checkpin';

// Initialize storage
const storage = new Storage('/path/to/project');
await storage.init();

// Load state
const projectState = await storage.loadProjectState();
const activeTask = await storage.getActiveTask();

// Save a note
await storage.addNote({
  id: 'note-123',
  content: 'User prefers dark mode',
  type: 'preference',
  confidence: 0.9,
  sources: [],
  created: new Date().toISOString(),
  status: 'active'
}, 'project');

// Extract from session
const sessionData = {
  id: 'session-123',
  messages: [...],
  // ...
};
const extracted = extractFromSession(sessionData);

Roadmap

• [x] Phase 1: MVP - Hooks + Basic Storage
• [ ] Phase 2: Smart Task Detection
• [ ] Phase 3: Self-Organizing Capabilities
• [ ] Phase 4: Skill Commands
• [ ] Phase 5: A2A Protocol Integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT