Give Claude a memory that lasts. Everything you tell it stays — searchable across conversations, private, on your machine.
Your memory lives in a local database — not the cloud. Default embeddings use a free Google key; go fully local and offline with Ollama.
You: "Remember I'm allergic to shellfish"
↓ stored locally
... weeks later, new conversation ...
Claude: (recalls your allergy before suggesting a recipe)
Persistent memory system for Claude Code — hybrid search (FTS5 + vector), message bus, task queue. Works as MCP server (stdio + HTTP).
स्टार
81
टूल
—
अपटाइम
—
Security update — 0.4.1 (Oct 2026). If you run HTTP mode (imprint-memory --http), upgrade: pip install -U imprint-memory.
Up to 0.4.0, requests from 127.0.0.1 skipped the token check. Cloudflare Tunnel forwards the real client IP so it stayed locked, but plain TCP forwarders (frp, ssh -R, socat, many port-forward services) make every outside request look local, so the memory was open to anyone with the URL. 0.4.1 always requires the token and won't start HTTP mode without one.
0.1.0 (and git installs from before 2026-05-17) let anyone in when no credentials were set and shipped a cc_execute tool that could drive your local Claude Code. If you ever exposed one of those, upgrade and assume the memory was readable.
0.4.0 and earlier also broke on install once mcp 2.x came out; 0.4.1 pins mcp<2.
What it does
Captures every turn automatically — each surface feeds the same
store through its own entry point: a Stop hook for Claude Code, the
Chrome sync extension for claude.ai, channel adapters for Telegram and
the like. Every message lands in a searchable log, gets segmented into
events, and multimodal-embedded (text + image). The LLM never needs to
"decide to remember" — it's already stored.
Hybrid search out of the box — keyword (FTS5/BM25) + semantic
(vector) + RRF rank fusion across memory / bank / chunk pools.
"What did I say about that project last week?" → it finds it.
Auto-surfaces context before you even ask — a
UserPromptSubmit hook calls surfacing_search on every prompt
and injects a <recall> block with up to ~6 related events.
Multimodal — images sent in a conversation get text + image
embeddings, so "the red screenshot I sent" lands on the right
message even if the caption doesn't mention "red".
Syncs your claude.ai chats — optional Chrome extension captures
your web conversations into the same memory store.
AI-flagged highlights(optional) — the LLM can call
memory_remember to bump a specific fact higher in search results,
but the system fully works without it.
Stays organised — facts can be pinned, tagged, and linked
(graph edges between memories). Importance can be tuned per-entry.
Speaks Chinese — full CJK search, time expressions like
昨天、上个月、去年冬天.
How it actually works
A common misconception: "the AI still has to choose what to
remember, right?" — No. The whole capture-and-recall pipeline
is automatic. Curation tools (memory_remember, pin, etc.) exist
and the LLM may use them for small quality boosts, but they sit
on top of an already-complete automatic system. Search, recall, and
auto-surfacing all work without any curation call ever being made.
Architecture at a glance
flowchart TB
subgraph CAPTURE["📥 Capture (automatic, every turn)"]
turn["any conversation turn<br/>(cc hook · claude.ai sync · telegram · app)"]
turn --> log["log_message → conversation_log"]
log --> mm["multimodal embed<br/>(text + image)"]
log -. scheduled .-> ch["chunker → events + summaries"]
ch --> ce["chunk_edges<br/>(Top-K similarity graph)"]
log --> fts["FTS5 + jieba CJK index"]
end
subgraph SEARCH["🔎 Search (automatic, on every memory_search call)"]
q["query"] --> rrf["vec cosine + BM25 + RRF fusion"]
mm --- rrf
ce --- rrf
fts --- rrf
rrf --> ranked["ranked results across memory/bank/chunk pools"]
end
subgraph SURFACE["✨ Surface (automatic, before LLM sees any prompt)"]
prompt["user prompt"] --> hook["UserPromptSubmit hook"]
hook --> ssearch["surfacing_search"]
ssearch --> recall["⟨recall⟩ block injected<br/>≈ 6 related events"]
end
subgraph CURATE["📝 Curate (optional — LLM or you call. System works fully without these)"]
rem["memory_remember(content)<br/>flag highlight fact"]
pn["memory_pin(id)<br/>no decay"]
tg["memory_add_tags / add_edge<br/>manual annotation"]
mt["find_stale / decay / delete<br/>bulk maintenance"]
end
rem -. boost ranking .-> rrf
pn -. boost ranking .-> rrf
tg -. boost ranking .-> rrf
Automatic pipeline — the whole system
What
How
Every message stored verbatim
A Claude Code Stop hook + claude.ai sync + channel adapters call log_message() on every in/out turn. No "decide to save" step.
Multimodal embed of images
When a message carries an upload header (e.g. 路径=/abs/path.jpg), _maybe_embed_image runs inline and writes a combined text+image vector
Segment conversations into "events"
incremental_chunk_update runs on a schedule, groups consecutive messages into chunks, generates a one-paragraph LLM summary + keywords per chunk
Top-K similarity graph between events
After each chunk batch, similarity edges are built so related events surface together in graph-mode retrieval
Hybrid search across all pools
memory_search runs vector cosine + BM25 keyword + RRF rank-fusion across memory / bank / chunk pools every call
Auto-surface relevant context on every prompt
A UserPromptSubmit hook calls surfacing_search before the LLM sees the prompt and injects a <recall> block with ~6 related events
FTS5 + CJK indexing
SQLite triggers + jieba segmentation; index stays synced with every write
A launchd job catches anything missed (e.g. embed API was briefly down)
Optional curation tools
The pipeline above is enough on its own. These extra MCP tools exist
so the LLM (or you) can annotate memories for slightly better
ranking — call them when useful, skip them entirely if you don't
care; the system works fully either way.
Tool
When
What it does
memory_remember(content)
LLM decides "this is a long-term ground-truth fact"
Stores it in the curated memories table so future searches surface it with a small ranking boost (e.g. "I'm lactose intolerant")
memory_pin(id)
A memory should never decay
Marks the row pinned — bypasses any importance/recency decay
Adds categorical tags or explicit relationships ("contradicts", "evolved from") between two memories
memory_find_stale, memory_decay, memory_delete
Periodic clean-up
Inspect old/low-recall entries, decay importance scores, hard-delete rows you no longer want
If your LLM never invokes any of these, conversations are still
captured, chunked, embedded, indexed, and reachable through
memory_search — you just don't get the small "this fact is a
highlight" ranking nudge.
Installs imprint-memory and registers the MCP server. You'll then need a
GOOGLE_API_KEY for embeddings — see Models & Cost
below (5-min, free, no card). Data lives in ~/.imprint/.
Manual install
pip install imprint-memory
claude mcp add -s user imprint-memory -- imprint-memory
export GOOGLE_API_KEY=... # for embeddings, see below
Restart Claude Code. That's it.
Prefer fully-local (no API keys)?
Set EMBED_PROVIDER=ollama BEFORE the first write, then:
ollama pull bge-m3 && ollama serve
You lose multimodal (text+image) — bge-m3 is text-only. See the
embedding consistency
note about why this choice must be made up front.
imprint-memory-capture reads the just-finished turn's transcript and writes
each message to conversation_log. Without it the Claude Code channel won't
auto-capture (claude.ai sync and other channel adapters have their own paths).
Auto-surfacing hook (optional)
Makes Claude automatically recall relevant memories when you ask something:
imprint-memory does NOT replace your main chat model — Claude /
ChatGPT / Gemini / whichever LLM you talk to keeps doing that job
unchanged. What imprint-memory runs internally is a small handful of
helper models that turn raw chat history into searchable memory:
one for embedding (turning text and images into vectors), one for
chunk summarization (the chunker's LLM that compresses each
conversation segment into a one-paragraph summary), and an optional
one for context compression. The helpers below are all that
imprint-memory itself calls — your main chat LLM and your API bill
for it are completely separate.
Default helper config is tuned to fit inside vendors' free tiers
for normal personal use — no payment card required, no billing to
enable, no surprise charges.
Sign up free at dash.cloudflare.com/sign-up (no card). Workers AI free tier is on by default. Account ID is in the dashboard URL. Create a token at /profile/api-tokens → "Create Token" → "Workers AI" template. export CF_ACCOUNT_ID=... CF_API_TOKEN=...
Chunk-summary LLM (alternative 1)
—
gemini-1.5-flash or gemini-2.0-flash
Google AI Studio
Free tier (~15 req/min)
Same GOOGLE_API_KEY as embedding. Set GEMINI_SUMMARY_MODEL to the Gemini model name
Chunk-summary LLM (alternative 2)
—
Any Ollama model
Local Ollama
$0, local
Slower / lower quality summaries; set OLLAMA_CHAT_MODEL accordingly
Context compression (compress.py)
Optional, separate script
qwen3:8b
Local Ollama
$0, local
Only if you actually use the compress.py CLI. brew install ollama && ollama pull qwen3:8b
Bottom line: the only thing strictly required to get up and running
is one embedding provider. If you set up Google for embedding,
chunk summarization can reuse the same GOOGLE_API_KEY. Daily personal
use never gets close to free-tier limits, and "enabling" Workers AI
or Google AI Studio is a single click — neither provider can charge
you without you explicitly switching plans.
⚠️ Embedding consistency — DO NOT MIX
The vector dimension MUST stay constant across the lifetime of one DB.
Provider / model
Dim
Multimodal?
Google gemini-embedding-2
3072
✓ text + image
OpenAI text-embedding-3-small
1536
text only
Ollama bge-m3
1024
text only
Switching EMBED_PROVIDER mid-stream means new vectors get a different
shape than old ones. Cosine similarity then returns 0 across the
boundary and search silently goes half-blind — FTS still works, but
the semantic channel is dead for everything written before the switch.
Pick once, before the first write. If you absolutely must switch:
run imprint-memory-reindex to rebuild curated memory + bank vectors, then
DELETE FROM conversation_vectors; on the DB and let the receiver's backfill
re-embed conversations incrementally (a full cloud re-embed can exceed
free-tier quotas).
MCP Tools (27 total)
Memory CRUD
Tool
What it does
memory_remember
Store a memory. Categories: facts (preferences, truths), events (things that happened), insights (reflections). Auto-deduplicates.
Without a hint, the LLM tends to call memory_search once and stop. But
memory_search only sees the chunk-level index — and the chunker's LLM
summaries can drop proper nouns (e.g. system names, paper titles, library
names). When that happens, memory_search returns nothing even though
the raw conversation_log still has 20+ matching messages.
Two-step search rule — drop this into your CLAUDE.md so the model falls
back automatically:
When you can't find past information, don't say "I don't remember"
until you've tried both steps:
1. memory_search(query) — unified entry, RRF across memory / bank / chunk pools
2. conversation_search(query) — raw conversation_log FTS5 fallback
(must hit if the word ever appeared in any message)
Configuration
All via environment variables. Defaults work out of the box for local use.
Variable
Default
Description
IMPRINT_DATA_DIR
~/.imprint
Where data lives
IMPRINT_DB
$IMPRINT_DATA_DIR/memory.db
Database path
TZ_OFFSET
0
Your timezone offset from UTC (hours)
IMPRINT_USER_NAME
User
Your name in conversation summaries
IMPRINT_AGENT_NAME
Assistant
AI name in conversation summaries
IMPRINT_LOCALE
en
Output language: en or zh
EMBED_PROVIDER
google
Embedding provider: google (default, 3072-dim multimodal), ollama (1024-dim local), openai, cloudflare. Pick once — see consistency warning above.
EMBED_MODEL
varies
Model for embeddings. Defaults: bge-m3 (Ollama), text-embedding-3-small (OpenAI), gemini-embedding-2 (Google)
OLLAMA_URL
http://localhost:11434
Ollama server URL
OPENAI_API_KEY
unset
For OpenAI embeddings
EMBED_API_BASE
https://api.openai.com
OpenAI-compatible API base
GOOGLE_API_KEY
unset
For Google Gemini embeddings
GOOGLE_API_KEYS
unset
Multiple Google keys (comma-separated, round-robin)
CF_ACCOUNT_ID
unset
Cloudflare account for query expansion
CF_API_TOKEN
unset
Cloudflare API token
IMPRINT_HTTP_HOST
127.0.0.1
HTTP mode bind address (tunnels connect to localhost; use 0.0.0.0 only for LAN/Docker)
git clone https://github.com/Qizhan7/imprint-memory.git
cd imprint-memory
pip install -e '.[all]'
pytest
Acknowledgements
Built on top of these open-source libraries:
JioNLP by dongrixinyu (Apache 2.0) — powers the natural-language time parsing in _extract_time_intent (昨天/上周/5月15日 → date ranges via jionlp.ner.extract_time). Without it, queries like "what we talked about yesterday" couldn't pin a real time window.
jieba (MIT) — Chinese tokenisation for FTS5 indexing and keyword extraction.
NumPy (BSD) — vector-space matrix operations for the graph build (Top-K edges, MMR diversification).
Embedding providers: Google Gemini Embedding 2 (multimodal), OpenAI text-embedding-3-small, or local Ollama bge-m3 — configured via EMBED_PROVIDER.
License
AGPL-3.0 — free for personal use; commercial use requires open-sourcing your entire project under AGPL.
imprint-memory
让 Claude 记住你说过的话。下次聊天还在,搜得到,全部存在本地。
记忆存在本地数据库——不在云端。默认 embedding 用一把免费 Google key;想完全本地 + 离线就切到 Ollama。
底线:开起来绝对必需的只有一个嵌入服务。如果你用了
Google 做嵌入,chunk 摘要可以直接复用同一把 GOOGLE_API_KEY。日常
个人使用根本碰不到免费档上限,"启用" Workers AI 或 Google AI Studio
都是点一下(不要卡),两边都不可能在你没主动换套餐的情况下扣钱。
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
Imprint Memory कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या Imprint Memory के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Imprint Memory कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
Imprint Memory stdio पर लोकल चलता है।
Imprint Memory की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-10-28 को हुई। Persistent memory system for Claude Code — hybrid search (FTS5 + vector), message bus, task queue. Works as MCP server (stdio + HTTP).