Imprint

Persistent memory for AI coding agents — every session builds on the last.

Features · How It Works · Install · Tech Stack · Development

What is Imprint?

Imprint is a plugin for Claude Code that gives your AI agent persistent memory across sessions. Every tool call, decision, and discovery is captured, compressed via LLM, indexed for search, and injected as context into future sessions.

No Docker. No external databases. Single Go binary + SQLite.

Inspired by agentmemory (Node.js + Docker) and MemPalace (Python + ChromaDB), rebuilt from scratch in Go with ideas from both: agentmemory's observation pipeline and UI, MemPalace's 4-layer memory stack, query sanitization, and write-ahead log.

Features

How It Works

graph TD
    HOOK["Claude Code Hook<br/><i>SessionStart, PostToolUse, etc.</i>"]
    ENSURE["ensure-server<br/><i>auto-start, 10s timeout, logs errors</i>"]
    OBSERVE["/imprint/observe<br/><i>rate-limit, dedup, privacy scrub</i>"]
    COMPRESS["LLM Compress<br/><i>type, title, narrative, importance</i>"]
    INDEX["BM25 + Vector Index<br/><i>Bleve full-text + cosine similarity</i>"]
    GRAPH["Knowledge Graph<br/><i>entities, relations, BFS traversal</i>"]
    SCHEDULER["Background Scheduler<br/><i>summarize + consolidate every 5min</i>"]
    CONTEXT["Context Builder<br/><i>token-budgeted XML injection</i>"]
    SESSION["New Session<br/><i>SessionStart hook fires</i>"]
    MCP["MCP Tools<br/><i>memory_recall, memory_save, etc.</i>"]
    UI["Web UI<br/><i>http://localhost:3111</i>"]

    HOOK --> ENSURE
    ENSURE --> OBSERVE
    OBSERVE --> COMPRESS
    COMPRESS --> INDEX
    COMPRESS --> GRAPH
    INDEX --> SCHEDULER
    SCHEDULER -->|"memories, lessons, actions"| INDEX
    SESSION --> CONTEXT
    CONTEXT -->|"stdout injection"| HOOK
    MCP --> INDEX
    UI --> INDEX

    style HOOK fill:#F97316,color:#fff,stroke:none,rx:12
    style ENSURE fill:#2D8E5E,color:#fff,stroke:none,rx:12
    style OBSERVE fill:#2B7BB5,color:#fff,stroke:none,rx:12
    style COMPRESS fill:#7E44A8,color:#fff,stroke:none,rx:12
    style INDEX fill:#2B7BB5,color:#fff,stroke:none,rx:12
    style GRAPH fill:#7E44A8,color:#fff,stroke:none,rx:12
    style SCHEDULER fill:#B8860B,color:#fff,stroke:none,rx:12
    style CONTEXT fill:#2D8E5E,color:#fff,stroke:none,rx:12
    style SESSION fill:#F97316,color:#fff,stroke:none,rx:12
    style MCP fill:#1A1612,color:#fff,stroke:none,rx:12
    style UI fill:#1A1612,color:#fff,stroke:none,rx:12

The Pipeline

1. Capture — 11 compiled Go hooks intercept Claude Code events (tool use, prompts, errors, task completions, permission prompts)
2. Scrub — 16 regex patterns strip API keys, tokens, JWTs, and secrets before storage
3. Pre-extract (v1.2.0) — A deterministic regex pass pulls file paths, PascalCase concepts, URLs, error markers, and git refs out of the observation. The LLM never has to re-extract the easy mechanical entities, cutting Haiku spend.
4. Compress — Background workers send the remaining work to an LLM (Anthropic / OpenRouter / llama.cpp with circuit breaker + fallback), producing structured summaries with type, title, narrative, importance (1-10), concepts (merged with the pre-pass), and files (already extracted)
5. Index — Each compressed observation is immediately indexed into Bleve (BM25) inside the worker. On startup, an empty BM25 with rows in the DB triggers a self-heal reindex of every compressed observation
6. Schedule — Background scheduler runs summarize + consolidate + action extraction + graph extract periodically during active sessions. Graph extract is incremental (v1.5.0): only obs without graph_extracted_at are processed, capped per tick to control Haiku cost.
7. Extract — LLM extracts entities (files, functions, concepts) and relations into a knowledge graph
8. Inject — On new sessions, token-budgeted context blocks are built from recent summaries, high-importance observations, and strong memories. Each item carries an inline metadata sufix (★N · Xd or iN · Xd) so the assistant has strength + age signal without a roundtrip to the DB.

Hook Architecture

Install

Option 1: Claude Code Plugin Marketplace (recommended)

# Add the marketplace (one time)
/plugin marketplace add JohnPitter/imprint

# Install the plugin
/plugin install imprint@imprint-tools

Restart Claude Code once. The SessionStart hook downloads the prebuilt binaries for your platform (darwin-arm64, darwin-amd64, linux-amd64, linux-arm64, windows-amd64) from the matching GitHub release on first run. Subsequent sessions reuse the cached binaries (~ms).

No Go or Node toolchain required. Releases are signed with sha256 checksums (latest).

Option 2: Build from source

For development, plugin authoring, or unsupported platforms:

git clone https://github.com/JohnPitter/imprint.git
cd imprint
go run ./cmd/install            # build all binaries into plugin/bin/

Add the local plugin directly:

claude --plugin-dir $(pwd)/plugin

Legacy direct install

If you prefer the pre-marketplace flow that writes hooks/MCP straight into ~/.claude/settings.json (no marketplace required), pass --register:

go run ./cmd/install --register

This is kept for backwards compatibility. New users should use Option 1.

What Happens After Install

1. Open a new Claude Code session
2. The SessionStart hook auto-starts the Imprint server
3. Every tool use is captured automatically
4. Open http://localhost:3111 to see the dashboard
5. MCP tools (memory_recall, memory_save, etc.) are available to Claude

Uninstall

cd imprint
go run ./cmd/install --uninstall

Tech Stack

Development

Setup

git clone https://github.com/JohnPitter/imprint.git
cd imprint

# Install frontend deps
cd frontend && npm install && cd ..

# Run dev server
go run .

# Run tests
go test ./... -count=1

# Build production
cd frontend && npm run build && cd ..
go build -ldflags="-s -w" -o imprint.exe .

# Build hooks + MCP
go run ./cmd/install --build-only

Structure

imprint/
  main.go                    # HTTP server + scheduler entrypoint
  internal/
    config/                  # Config loader + user settings
    store/                   # SQLite stores (17 stores, 28 tables)
    search/                  # BM25 + vector + hybrid search
    llm/                     # Provider interface + Anthropic/OpenRouter/llama.cpp
    pipeline/                # Compress, summarize, consolidate, graph extract
    privacy/                 # Secret scrubbing (16 regex patterns)
    service/                 # Business logic layer + scheduler
    server/                  # HTTP handlers + Chi router
    mcp/                     # MCP JSON-RPC server
    hooks/                   # Shared hook library
  cmd/
    hooks/                   # 11 hook binaries
    ensure-server/           # cross-platform auto-start launcher invoked by SessionStart
    mcp-server/              # Standalone MCP binary
    install/                 # One-command installer
  frontend/                  # Svelte 3 + TypeScript UI
  plugin/                    # Claude Code plugin structure

Environment Variables

Privacy

• All data stored locally in ~/.imprint/
• 16 regex patterns scrub API keys, tokens, JWTs, passwords before storage
• No telemetry, no tracking, no external calls (except configured LLM API)
• Open source for audit

Acknowledgments

Imprint stands on the shoulders of two excellent projects:

• agentmemory by Rohit Ghumare — the original persistent memory system for AI coding agents. Imprint adopted its observation capture pipeline, hook architecture, LLM compression approach, and web dashboard concept.
• MemPalace — a verbatim-first memory system with innovative ideas. Imprint adopted its 4-layer memory stack with token budgets, query sanitizer for system prompt contamination, write-ahead audit log, heuristic memory classification, and temporal knowledge graph invalidation.

License

MIT License — use freely.