imprint

README

imprint

Portable markdown memory for AI agents

English · 中文

Durable preferences from normal conversation land in .imprint/memory/. You talk normally; the agent maintains the vault — classifies each turn, recalls before the next edit.

	When	Example
ADD	New long-term preference	Naming rule, workflow, architecture boundary
REINFORCE	Same policy again	“Yes, still PascalCase for exports”
SUPERSEDE	Policy changed	Narrow scope, widen scope, replace claim
IGNORE	Task-only turn	One-off refactor, chit-chat, secrets

When the user rejects a stored rule (“don’t record that”), the agent finds and calls forget — not one of the four classifications above. See Memory writes.

Vault stores claim, evidence, and optional doc pointers (sources). Shelves indexes markdown under roots for BM25 recall alongside rules.

---

Quick start

go install github.com/SteamedBread2333/imprint/cmd/imprint@latest
go install github.com/SteamedBread2333/imprint/cmd/imprint-mcp@latest
cd your-project && imprint init

Merge docs/examples/cursor-mcp.json into .cursor/mcp.json and restart the editor. CLI fallback: imprint --json.

	You	imprint
1	Install + init	Writes editor rules (Cursor, Claude Code, Codex, Trae, Workbuddy)
2	Speak normally	Agent find (vault + shelves) → classify → add/reinforce/… (optional sources)
3	Browser audit (optional)	imprint up → imprint desk open

flowchart TB
  U((User<br/>speaks normally))

  subgraph Agent["Agent · imprint-mcp"]
    direction TB
    F["find(scope, query)"]
    C{"Classify<br/>ADD · REINFORCE · SUPERSEDE · IGNORE"}
    W["add / supersede<br/>optional sources"]
    R["find again before coding · cite [r-id]"]
  end

  subgraph Store["imprint storage"]
    direction LR
    Vault[(".imprint/memory/<br/>claim · evidence · sources")]
    Shelves[(".shelves/.cache/<br/>roots doc BM25")]
  end

  subgraph FindOut["one find call"]
    direction LR
    FR["rules<br/>resolved_sources"]
    FD["documents<br/>snippet"]
    FL["links"]
  end

  subgraph Audit["Optional · human audit"]
    H((You)) --> Desk["desk · show"]
  end

  UP["imprint up"] -.->|host indexes| Shelves

  U -->|speak / task| Agent
  F --> Vault
  F --> Shelves
  Vault --> FR
  Shelves --> FD
  Vault --> FL
  Shelves --> FL
  FR & FD & FL --> C
  C -->|persist| W
  W --> Vault
  R --> F
  Desk --> Vault
  Desk --> Shelves

Before coding (sequence)

sequenceDiagram
  participant U as User
  participant A as Agent
  participant V as vault
  participant S as shelves

  U->>A: new task / continue coding
  A->>V: find(scope, query)
  V->>S: BM25 docs (when shelves on)
  V-->>A: rules · documents · links
  A->>A: code from imprints + excerpts
  Note over A: cite [r-id] and doc path

---

CLI

Global flags: --vault PATH · --global · --json (machine-readable stdout for agents)

Everyday — vault

Read and write the vault directly from the CLI.

Command	What it does
imprint init	Write editor agent rules
imprint find [--scope a,b] [--query TEXT]	Recall imprints (scope AND); with query + shelves → also documents, links
imprint add CLAIM --scope a,b --text ORIG	Create an imprint (MCP may include sources linking docs)
imprint reinforce ID [--evidence TEXT]	Strengthen a rule (+0.1 confidence)
imprint supersede OLD --claim NEW --scope a,b	Replace a rule; old → superseded
imprint forget ID	Delete permanently
imprint list · show · get ID	Browse and inspect
imprint sweep · export	Decay stale rules · dump JSON

imprint find --scope go,naming --query PascalCase
imprint add "Use snake_case" --scope python,naming --text "user said snake_case"
imprint get r-2026-09-11-001

Local stack

Command	What it does
imprint up	Start the local stack (vault API, shelves, enabled desk, …)
imprint down	Stop the local stack
imprint desk open	Open desk in the browser (requires up first)
imprint status	Snapshot of running services

imprint up && imprint desk open
# when done:
imprint down

After editing imprint.yaml: run down then up.

Advanced: split host / plugin control (debug)

Command	What it does
imprint host start / host stop	Host only (includes shelves)
imprint plugin start / plugin stop	External plugins only
plugin list · enable · disable	Toggle plugins in yaml

Shelves is top-level host config (shelves: in imprint.yaml). See docs/shelves-builtin.md.

Debug & advanced

Command	What it does
imprint host serve [--listen ADDR]	Foreground host (Ctrl+C)
imprint migrate-shards [--dry-run]	Import legacy imprint-*.md into vault.db (one-off)
imprint clear --confirm --yes	Delete every rule — irreversible
imprint version	Print version

Run imprint --help or imprint help <cmd> for full flags.

---

Vault layout

Default: ./.imprint/memory/ (walk up for .imprint/). --global → ~/.imprint. Override with --vault or IMPRINT_VAULT.

.imprint/
  imprint.yaml          # host + shelves.roots + plugins
  memory/vault.db       # SQLite vault (rules, evidence, edges, sources)
  .shelves/.cache/      # doc index under roots (SQLite, gitignored)
docs/                   # typical root
.cursor/rules/          # typical root

Rules live in memory/vault.db. IDs: r-YYYY-MM-DD-NNN. Status: active | dormant | superseded. supersede marks old rules superseded; sweep decays stale rules to dormant; forget deletes. Interactive rule graph: imprint desk open (host GET /graph).

---

Shelves & desk

	Where it runs	Config
Shelves	host	shelves.enabled, config.roots in imprint.yaml
Desk	External plugin	plugins.desk + imprint-desk-plugin

Shelves indexes markdown under roots in imprint.yaml (e.g. docs/, .cursor/rules/). Before coding, find(scope, query) returns vault rules, document snippets, and links in one call. Local BM25 index.

roots lists which directories enter the index — scoped recall and fast rebuilds. See docs/shelves-builtin.md.

Linking: Vault sources point rules at doc paths or headings; get r-… returns resolved_sources. Design: docs/imprint-shelves-linking.md.

One MCP mount (imprint-mcp). With shelves on and find + query, the response includes rules, documents, and links.

---

Install & release

docker pull ghcr.io/steamedbread2333/imprint:latest   # or GitHub Releases binaries
make install          # from clone
make publish V=X.Y.Z  # tag + CI → Release + GHCR

Local builds without a tag print devel.

---

Documentation

Topic	English	中文
MCP mount	docs/mcp.md	docs/mcp.zh.md
Editor init	docs/editors.md	docs/editors.zh.md
Shelves & linking	docs/shelves-builtin.md · docs/imprint-shelves-linking.md	docs/shelves-builtin.zh.md · docs/imprint-shelves-linking.zh.md
Write loop & scenarios	docs/correction.md	docs/correction.zh.md

MCP examples (merge manually): cursor-mcp.json · cursor-mcp-global.json

---

Go module

import "github.com/SteamedBread2333/imprint/pkg/imprint"

v, _ := imprint.Open("./.imprint/memory")
v.Add("Use gofmt", []string{"go"}, "gofmt", 0.6)
v.Find([]string{"go"}, "", 5)

MIT