claude-imprint
Self-hosted AI agent system built on Claude Code. Multi-channel chat, persistent memory with semantic search, scheduled tasks, and a single-file dashboard.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/qizhan7--claude-imprint)HTML
<a href="/listings/qizhan7--claude-imprint"><img src="/api/listings/qizhan7--claude-imprint/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/Qizhan7/claude-imprint.git cd claude-imprint python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt # Register memory MCP server claude mcp add -s user imprint-memory -- imprint-memory # Start dashboard python3 packages/imprint_dashboard/dashboard.py # → http://localhost:3000
You now have persistent memory in Claude Code. Add modules below for more.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 249 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Claude Imprint
- A self-hosted system that gives Claude persistent memory, multi-channel messaging, and automation. Talk to it from Claude Code, Claude.ai, or Telegram — it remembers everything and shares context across channels. Other channels (Discord, Slack, etc.) can be added via their own MCP servers.
- Built for **Claude Code Pro/Max subscribers**. Uses only official Claude Code features — no API costs, no third-party auth.
- > ⚠️ **Security notice (Oct 2026).** This repo was built in May 2026. If you set up the Claude.ai integration (`imprint-memory --http`) back then, upgrade: `pip install -U imprint-memory` (0.4.1+).
- > - Older imprint-memory let any request coming from `127.0.0.1` skip the token. Cloudflare Tunnel passes the real client IP, so the setup below stayed locked, but plain TCP forwarders (frp, ssh -R, socat, port-forward services) make every outside request look local. 0.4.1 always requires the token and won't start HTTP mode without one.
- > - imprint-memory 0.1.0 / git installs from before 2026-05-17 let anyone in when no credentials were set and included a `cc_execute` tool that could drive your local Claude Code. If you exposed one of those, upgrade and assume the memory was readable.
- > - `cron-task.sh` runs Claude Code with `--dangerously-skip-permissions`. Anything those prompts read (web pages, email, messages) can steer it, so keep cron prompts on trusted input.
- >
- > 中文:五月装过并开了 Claude.ai 远程(`--http`)的,请 `pip install -U imprint-memory` 升到 0.4.1。旧版对本机来的请求不验 token,用 frp / ssh -R / 花生壳这类纯转发穿透时等于没锁;最早的 0.1.0 没配凭据时谁都能进。定时任务脚本用了 `--dangerously-skip-permissions`,只喂可信的输入。
- > **Just want persistent memory?** The memory system is a standalone package: [imprint-memory](https://github.com/Qizhan7/imprint-memory). Install it alone with `pip install` — no need for the full Imprint stack. This repo adds multi-channel messaging, automation, dashboard, and everything else on top.
- ## Features
- ### 🧠 Memory
- - **Hybrid search** — FTS5 full-text + bge-m3 vector embeddings + exact-match keyword, fused with RRF ranking and time-decay scoring. Replaces Claude Code's built-in file-based memory.
- - **CJK support** — Chinese/Japanese/Korean text segmented with jieba for accurate full-text search.
- - **Unified across interfaces** — The same SQLite backend serves Claude Code (stdio MCP) and Claude.ai (HTTP MCP via Cloudflare Tunnel). Memories saved in one are instantly searchable from the other.
- - **Categorized storage** — Memories tagged by type (facts, events, tasks, experience) and source. Search by category or let hybrid search find the best match.
- - **Knowledge bank** — Long-form structured knowledge in Markdown files (`memory/bank/`). Preferences, relationships, technical experience — all indexed and included in semantic search.
- - **Daily logs** — Automatic daily journals. Pre-compaction hooks capture context before it's compressed. Nothing gets lost.
- - **Starlog** — A timeline of your day across every window. After each stretch of conversation a small model writes one first-person line (`14:20 [telegram] …`); every half hour the lines are woven into short paragraphs, merging the same event seen from different windows. Every new session starts out knowing what the other windows did today.
- ### 💬 Multi-Channel
- - **Telegram** (primary) — Full-featured: chat, file sharing, heartbeat notifications, morning briefings, direct messaging from Claude.ai. Uses Anthropic's official Claude Code Telegram plugin.
- - **Claude.ai** — Connect via Cloudflare Tunnel + OAuth. Full memory access from the web and mobile apps.
- - **Cross-channel context** — Messages flow in from all sources. Claude keeps a shared timeline of what happened where. When you switch devices, it already knows the context.
- - **Pluggable channels** — The system auto-detects any Claude Code channel plugin (Discord, Slack, etc.). Just install the MCP server and messages are automatically logged, tagged, and searchable.
- ### 🎮 Remote Control (requires [Chat Integration](#chat-integration-claudeai--local-memory) + additional MCP packages)
- - **Direct Telegram messaging** — Claude.ai sends to your Telegram via Bot API. Requires `imprint_telegram` MCP (see [Telegram setup](#telegram)).
- - **System monitor** — Check CPU, RAM, disk, running services. Requires `imprint_utils` MCP.
- - **Webpage reader** — Fetch and read any URL. Requires `imprint_utils` MCP.
- - **Spotify control** — Play, pause, skip, volume. Requires `imprint_utils` MCP. macOS only (AppleScript).
- ### ⚡ Automation
- - **Scheduled tasks** — Morning briefing, reminders, nightly memory consolidation. Customizable cron prompt templates.
- - **Heartbeat agent** — Wakes your live Telegram session on a timer (pastes a pulse into it via tmux), so the Claude that checks in is the same one you've been talking to, with full context. Falls back to a one-off headless run if there's no session.
- - **Hooks** — Pre-compaction context saver + post-response conversation logger with auto-compression.
- ### 📊 Dashboard
- - **Control panel** — Single-file FastAPI app (localhost:3000). Start/stop services, browse memories, view scheduled tasks, conversation stream stats, and a GitHub-style interaction heatmap.
- 
- ## Platform support
- | Feature | macOS | Linux / Cloud |
- |---------|-------|---------------|
- | Memory system, dashboard, hooks, cron | ✅ | ✅ |
- | Telegram, Claude.ai integration | ✅ | ✅ |
- | `start.sh` / `stop.sh` | ✅ Terminal windows | ✅ Background processes |
- | Spotify control | ✅ | ❌ AppleScript only |
- ### Cloud server deployment
- Core features (memory, HTTP server, dashboard, Telegram, heartbeat, cron) work on Linux cloud servers. Claude Code runs as a CLI tool — a basic VPS (1 CPU, 1GB RAM) is sufficient; the AI inference happens on Anthropic's servers, not yours.
- ```bash
- # Quick start on a cloud server
- git clone https://github.com/Qizhan7/claude-imprint.git && cd claude-imprint
- python3 -m venv .venv && source .venv/bin/activate
- pip install -r requirements.txt
- # Authenticate Claude Code (Max Plan OAuth token)
- mkdir -p ~/.claude && echo "your-token" > ~/.claude/cron-token
- ./start.sh # starts all services as background processes
- ./stop.sh # stops everything
- ```
- For production deployments, systemd service templates are provided in [`deploy/`](deploy/). See [`deploy/README.md`](deploy/README.md) for full instructions.
- ## Prerequisites
- - **Python 3.10+** (required by imprint-memory for type hint syntax)
- - **Claude Code** (Pro or Max subscription)
- - **macOS or Linux**
- ## Quick start
- ```bash
- git clone https://github.com/Qizhan7/claude-imprint.git
- cd claude-imprint
- python3 -m venv .venv && source .venv/bin/activate
- pip install -r requirements.txt
- # Register memory MCP server
- # Use the venv path so Claude Code finds it even when the venv isn't activated
- claude mcp add -s user imprint-memory -- "$(pwd)/.venv/bin/imprint-memory"
- # Start dashboard
- python3 packages/imprint_dashboard/dashboard.py
- # → http://localhost:3000
- ```
- You now have persistent memory in Claude Code. Add modules below for more.
- ## Modules
- ### Chat integration (Claude.ai → local memory)
- Connect Claude.ai to your local memory via Cloudflare Tunnel + HTTP MCP.
- ```bash
- # 1. Generate OAuth credentials (HTTP mode refuses to start without them)
- python3 scripts/generate_oauth.py # → ~/.imprint-oauth.json
- # 2. Start HTTP server
- imprint-memory --http # → 127.0.0.1:8000, bearer token always required
- # 3. Expose via tunnel
- cloudflared tunnel --url http://localhost:8000
- # 4. Claude.ai → Settings → Connectors → Add Custom Connector
- # Enter tunnel URL + client_id / client_secret from ~/.imprint-oauth.json
- ```
- Use Cloudflare Tunnel (or anything that forwards the client IP). Needs imprint-memory 0.4.1+; on older versions a plain TCP forwarder bypasses the token.
- ### Telegram
- ```bash
- claude /telegram:configure # once: bot token + pairing
- ./start.sh # runs the channel session in tmux (session "imprint-tg")
- tmux attach -t imprint-tg # watch it; Ctrl-b d to detach
- ```
- The session is the stock `claude --permission-mode auto --channels plugin:telegram@claude-plugins-official`, just hosted in tmux so the heartbeat can reach it. Without tmux it still works, but the heartbeat falls back to headless mode.
- ### Automation
- ```bash
- # Heartbeat agent — pastes a pulse into the tmux Telegram session every HEARTBEAT_INTERVAL
- python3 packages/imprint_heartbeat/agent.py
- # Cron tasks — use prompt templates in cron-prompts/
- bash cron-task.sh morning-briefing cron-prompts/morning-briefing.md
- ```
- How a pulse works: the agent pastes a short `[Heartbeat · <time>]` message (current time + your `HEARTBEAT.md` checklist) into the channel session and presses Enter. Claude handles it like any other turn, with the whole conversation in context, and messages you through the Telegram reply tool only if it has something to say. If the session is sitting on a permission prompt, that tick is skipped so the pulse never answers a dialog for you. Hooks log pulses as `heartbeat`, not as your messages.
- Cron runs with a bare environment: `cron-task.sh` puts the project's `.venv/bin` on PATH (override with `IMPRINT_VENV`) and reads a long-lived token from `~/.claude/cron-token` (`claude setup-token` makes one).
- Cron templates: `morning-briefing.md`, `drink-water.md`, `health-check.md`, `nightly-consolidation.md`, `weekly-memory-audit.md`. Edit to fit your style and schedule with crontab.
- > **Note:** Templates that use `send_telegram` or `system_status` need the full MCP config. The runner auto-detects `cron-mcp-full.json` (includes telegram + utils) if present, otherwise falls back to `cron-mcp.json` (memory only).
- ### Hooks
- Add to `~/.claude/settings.json` (replace `/path/to/claude-imprint`):
- ```json
- {
- "hooks": {
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/pre-compact-flush.sh" }] }],
- "Stop": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/post-response.sh" }] }],
- "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/session-start.sh" }] }]
- }
- }
- ```
- PreCompact saves context before compaction; Stop logs each turn and feeds the starlog; SessionStart hands each new session today's starlog. The hooks pick up `.venv/` in the project automatically (or set `IMPRINT_VENV`).
- ### Starlog
- Needs the Stop and SessionStart hooks above. Files live in `~/.imprint/starlog/`:
- ```
- timeline-2026-10-20.md raw lines, one per stretch of conversation
- - 14:20 [telegram] Planned a matcha basque cheesecake for her friend's birthday
- - 14:31 [cc·my-app] Fixed the login redirect loop; tests pass again
- arranged-2026-10-20.md the same day woven into paragraphs
- ```
- - **Lines** come from the Stop hook. It waits for enough new text (400 chars) and at most one line per window every 10 minutes, then asks `claude -p --model haiku` for one sentence. That runs on your own subscription, with no tools, no MCP and no saved session. If hooks can't see your login, it uses `~/.claude/cron-token`.
- - **Arranging** runs before every heartbeat, or from cron: `*/30 * * * * cd /path/to/claude-imprint && .venv/bin/python packages/imprint_starlog/starlog.py arrange`. Earlier paragraphs stay frozen; only the latest one can be revised to absorb something that continues it. If the model call fails, lines are kept raw.
- - **New sessions** get today's paragraphs, the tail of yesterday and the lines not woven in yet (budget `STARLOG_INJECT_CHARS`, default 8000). The long-running Telegram session gets other windows' new lines inside each heartbeat pulse.
- - `python3 packages/imprint_starlog/starlog.py show` prints today. The day starts at `STARLOG_DAY_START` (default 5am), so a late night still counts as the same day. `STARLOG_DISABLE=1` turns it off.
- ### Adding other channels (Discord, Slack, etc.)
- The system auto-detects any Claude Code channel plugin. No code changes needed — just install the channel MCP and everything works:
- 1. **Install the channel's MCP server** (e.g. a Discord MCP from the community)
- 2. **Register it in `.mcp.json`** alongside imprint-memory
- 3. **Start Claude Code** with both the channel and imprint-memory loaded
- What happens automatically:
- - **Memory** — `memory_remember`, `memory_search`, etc. work immediately
- - **Conversation logging** — The post-response hook detects the new channel by name and tags all messages with the correct platform (e.g. `discord`)
- - **Cross-channel context** — Messages appear in `recent_context.md` and the CLAUDE.md AUTO section, visible to all other channels
- - **Search** — Use `conversation_search(query)` for all platforms, or `search_channel(query, "discord")` for a specific one
- - **Dashboard** — Stream stats show the new platform automatically; unknown platforms get a neutral color tag
- - **RRF hybrid search** — Works across all platforms, no configuration needed
- ### Semantic search (optional)
- ```bash
- ollama pull bge-m3 && ollama serve
- ```
- Without this, keyword search still works — you just don't get vector similarity.
- ## Configuration
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `IMPRINT_DATA_DIR` | `~/.imprint` | Directory for memory.db and files |
- | `TZ_OFFSET` | `0` | UTC offset (e.g. `12`, `-5`) |
- | `HEARTBEAT_INTERVAL` | `900` | Heartbeat interval (seconds) |
- | `HEARTBEAT_MODE` | `auto` | `channel` = paste into the tmux session, `headless` = one-off `claude -p`, `auto` = channel if the session is up |
- | `HEARTBEAT_TMUX_TARGET` | `imprint-tg` | tmux session hosting the Telegram channel |
- | `TELEGRAM_CHAT_ID` | unset | Chat the heartbeat should reply to |
- | `STARLOG_DAY_START` | `5` | Hour the starlog day starts (01:00 still counts as yesterday) |
- | `STARLOG_MODEL` | `haiku` | Model for starlog lines and arranging |
- | `STARLOG_INJECT_CHARS` | `8000` | Max starlog size handed to a new session |
- | `STARLOG_DISABLE` | unset | `1` turns the starlog off |
- | `TELEGRAM_BOT_TOKEN` | — | From @BotFather |
- | `TELEGRAM_CHAT_ID` | — | From @userinfobot |
- | `QUIET_START` / `QUIET_END` | `23` / `7` | No proactive messages during these hours |
- See [imprint-memory](https://github.com/Qizhan7/imprint-memory) for memory-specific config (embedding provider, model, etc).
- ## Customizing your Claude
- The system is shaped by a few Markdown files. See **[docs/customization.md](docs/customization.md)** for the full guide.
- The short version:
- | File | What it does | Who writes it |
- |------|-------------|---------------|
- | `~/.claude/CLAUDE.md` | Personality, preferences, rules — the brain | You |
- | `HEARTBEAT.md` | Heartbeat behavior + checklist | You |
- | `memory/bank/*.md` | Structured knowledge (preferences, experience, relationships) | You + Claude |
- | `MEMORY.md` | Auto-generated memory index | System |
- | `memory/YYYY-MM-DD.md` | Daily logs | System |
- ## Acknowledgements
- [imprint-memory](https://github.com/Qizhan7/imprint-memory) · [Anthropic](https://anthropic.com) · [Ollama](https://ollama.com) + [bge-m3](https://huggingface.co/BAAI/bge-m3)
- ## License
- [AGPL-3.0](LICENSE) — free for personal use; commercial use requires open-sourcing your entire project under AGPL.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.