Skip to content
Back to search

claude-imprint

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/qizhan7--claude-imprint/badge.svg)](/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

i

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.

  1. # Claude Imprint
  2. 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.
  3. Built for **Claude Code Pro/Max subscribers**. Uses only official Claude Code features — no API costs, no third-party auth.
  4. > ⚠️ **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+).
  5. > - 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.
  6. > - 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.
  7. > - `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.
  8. >
  9. > 中文:五月装过并开了 Claude.ai 远程(`--http`)的,请 `pip install -U imprint-memory` 升到 0.4.1。旧版对本机来的请求不验 token,用 frp / ssh -R / 花生壳这类纯转发穿透时等于没锁;最早的 0.1.0 没配凭据时谁都能进。定时任务脚本用了 `--dangerously-skip-permissions`,只喂可信的输入。
  10. > **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.
  11. ## Features
  12. ### 🧠 Memory
  13. - **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.
  14. - **CJK support** — Chinese/Japanese/Korean text segmented with jieba for accurate full-text search.
  15. - **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.
  16. - **Categorized storage** — Memories tagged by type (facts, events, tasks, experience) and source. Search by category or let hybrid search find the best match.
  17. - **Knowledge bank** — Long-form structured knowledge in Markdown files (`memory/bank/`). Preferences, relationships, technical experience — all indexed and included in semantic search.
  18. - **Daily logs** — Automatic daily journals. Pre-compaction hooks capture context before it's compressed. Nothing gets lost.
  19. - **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.
  20. ### 💬 Multi-Channel
  21. - **Telegram** (primary) — Full-featured: chat, file sharing, heartbeat notifications, morning briefings, direct messaging from Claude.ai. Uses Anthropic's official Claude Code Telegram plugin.
  22. - **Claude.ai** — Connect via Cloudflare Tunnel + OAuth. Full memory access from the web and mobile apps.
  23. - **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.
  24. - **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.
  25. ### 🎮 Remote Control (requires [Chat Integration](#chat-integration-claudeai--local-memory) + additional MCP packages)
  26. - **Direct Telegram messaging** — Claude.ai sends to your Telegram via Bot API. Requires `imprint_telegram` MCP (see [Telegram setup](#telegram)).
  27. - **System monitor** — Check CPU, RAM, disk, running services. Requires `imprint_utils` MCP.
  28. - **Webpage reader** — Fetch and read any URL. Requires `imprint_utils` MCP.
  29. - **Spotify control** — Play, pause, skip, volume. Requires `imprint_utils` MCP. macOS only (AppleScript).
  30. ### ⚡ Automation
  31. - **Scheduled tasks** — Morning briefing, reminders, nightly memory consolidation. Customizable cron prompt templates.
  32. - **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.
  33. - **Hooks** — Pre-compaction context saver + post-response conversation logger with auto-compression.
  34. ### 📊 Dashboard
  35. - **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.
  36. ![Dashboard](docs/dashboard.png)
  37. ## Platform support
  38. | Feature | macOS | Linux / Cloud |
  39. |---------|-------|---------------|
  40. | Memory system, dashboard, hooks, cron | ✅ | ✅ |
  41. | Telegram, Claude.ai integration | ✅ | ✅ |
  42. | `start.sh` / `stop.sh` | ✅ Terminal windows | ✅ Background processes |
  43. | Spotify control | ✅ | ❌ AppleScript only |
  44. ### Cloud server deployment
  45. 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.
  46. ```bash
  47. # Quick start on a cloud server
  48. git clone https://github.com/Qizhan7/claude-imprint.git && cd claude-imprint
  49. python3 -m venv .venv && source .venv/bin/activate
  50. pip install -r requirements.txt
  51. # Authenticate Claude Code (Max Plan OAuth token)
  52. mkdir -p ~/.claude && echo "your-token" > ~/.claude/cron-token
  53. ./start.sh # starts all services as background processes
  54. ./stop.sh # stops everything
  55. ```
  56. For production deployments, systemd service templates are provided in [`deploy/`](deploy/). See [`deploy/README.md`](deploy/README.md) for full instructions.
  57. ## Prerequisites
  58. - **Python 3.10+** (required by imprint-memory for type hint syntax)
  59. - **Claude Code** (Pro or Max subscription)
  60. - **macOS or Linux**
  61. ## Quick start
  62. ```bash
  63. git clone https://github.com/Qizhan7/claude-imprint.git
  64. cd claude-imprint
  65. python3 -m venv .venv && source .venv/bin/activate
  66. pip install -r requirements.txt
  67. # Register memory MCP server
  68. # Use the venv path so Claude Code finds it even when the venv isn't activated
  69. claude mcp add -s user imprint-memory -- "$(pwd)/.venv/bin/imprint-memory"
  70. # Start dashboard
  71. python3 packages/imprint_dashboard/dashboard.py
  72. # → http://localhost:3000
  73. ```
  74. You now have persistent memory in Claude Code. Add modules below for more.
  75. ## Modules
  76. ### Chat integration (Claude.ai → local memory)
  77. Connect Claude.ai to your local memory via Cloudflare Tunnel + HTTP MCP.
  78. ```bash
  79. # 1. Generate OAuth credentials (HTTP mode refuses to start without them)
  80. python3 scripts/generate_oauth.py # → ~/.imprint-oauth.json
  81. # 2. Start HTTP server
  82. imprint-memory --http # → 127.0.0.1:8000, bearer token always required
  83. # 3. Expose via tunnel
  84. cloudflared tunnel --url http://localhost:8000
  85. # 4. Claude.ai → Settings → Connectors → Add Custom Connector
  86. # Enter tunnel URL + client_id / client_secret from ~/.imprint-oauth.json
  87. ```
  88. 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.
  89. ### Telegram
  90. ```bash
  91. claude /telegram:configure # once: bot token + pairing
  92. ./start.sh # runs the channel session in tmux (session "imprint-tg")
  93. tmux attach -t imprint-tg # watch it; Ctrl-b d to detach
  94. ```
  95. 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.
  96. ### Automation
  97. ```bash
  98. # Heartbeat agent — pastes a pulse into the tmux Telegram session every HEARTBEAT_INTERVAL
  99. python3 packages/imprint_heartbeat/agent.py
  100. # Cron tasks — use prompt templates in cron-prompts/
  101. bash cron-task.sh morning-briefing cron-prompts/morning-briefing.md
  102. ```
  103. 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.
  104. 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).
  105. 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.
  106. > **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).
  107. ### Hooks
  108. Add to `~/.claude/settings.json` (replace `/path/to/claude-imprint`):
  109. ```json
  110. {
  111. "hooks": {
  112. "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/pre-compact-flush.sh" }] }],
  113. "Stop": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/post-response.sh" }] }],
  114. "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/session-start.sh" }] }]
  115. }
  116. }
  117. ```
  118. 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`).
  119. ### Starlog
  120. Needs the Stop and SessionStart hooks above. Files live in `~/.imprint/starlog/`:
  121. ```
  122. timeline-2026-10-20.md raw lines, one per stretch of conversation
  123. - 14:20 [telegram] Planned a matcha basque cheesecake for her friend's birthday
  124. - 14:31 [cc·my-app] Fixed the login redirect loop; tests pass again
  125. arranged-2026-10-20.md the same day woven into paragraphs
  126. ```
  127. - **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`.
  128. - **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.
  129. - **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.
  130. - `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.
  131. ### Adding other channels (Discord, Slack, etc.)
  132. The system auto-detects any Claude Code channel plugin. No code changes needed — just install the channel MCP and everything works:
  133. 1. **Install the channel's MCP server** (e.g. a Discord MCP from the community)
  134. 2. **Register it in `.mcp.json`** alongside imprint-memory
  135. 3. **Start Claude Code** with both the channel and imprint-memory loaded
  136. What happens automatically:
  137. - **Memory** — `memory_remember`, `memory_search`, etc. work immediately
  138. - **Conversation logging** — The post-response hook detects the new channel by name and tags all messages with the correct platform (e.g. `discord`)
  139. - **Cross-channel context** — Messages appear in `recent_context.md` and the CLAUDE.md AUTO section, visible to all other channels
  140. - **Search** — Use `conversation_search(query)` for all platforms, or `search_channel(query, "discord")` for a specific one
  141. - **Dashboard** — Stream stats show the new platform automatically; unknown platforms get a neutral color tag
  142. - **RRF hybrid search** — Works across all platforms, no configuration needed
  143. ### Semantic search (optional)
  144. ```bash
  145. ollama pull bge-m3 && ollama serve
  146. ```
  147. Without this, keyword search still works — you just don't get vector similarity.
  148. ## Configuration
  149. | Variable | Default | Description |
  150. |----------|---------|-------------|
  151. | `IMPRINT_DATA_DIR` | `~/.imprint` | Directory for memory.db and files |
  152. | `TZ_OFFSET` | `0` | UTC offset (e.g. `12`, `-5`) |
  153. | `HEARTBEAT_INTERVAL` | `900` | Heartbeat interval (seconds) |
  154. | `HEARTBEAT_MODE` | `auto` | `channel` = paste into the tmux session, `headless` = one-off `claude -p`, `auto` = channel if the session is up |
  155. | `HEARTBEAT_TMUX_TARGET` | `imprint-tg` | tmux session hosting the Telegram channel |
  156. | `TELEGRAM_CHAT_ID` | unset | Chat the heartbeat should reply to |
  157. | `STARLOG_DAY_START` | `5` | Hour the starlog day starts (01:00 still counts as yesterday) |
  158. | `STARLOG_MODEL` | `haiku` | Model for starlog lines and arranging |
  159. | `STARLOG_INJECT_CHARS` | `8000` | Max starlog size handed to a new session |
  160. | `STARLOG_DISABLE` | unset | `1` turns the starlog off |
  161. | `TELEGRAM_BOT_TOKEN` | — | From @BotFather |
  162. | `TELEGRAM_CHAT_ID` | — | From @userinfobot |
  163. | `QUIET_START` / `QUIET_END` | `23` / `7` | No proactive messages during these hours |
  164. See [imprint-memory](https://github.com/Qizhan7/imprint-memory) for memory-specific config (embedding provider, model, etc).
  165. ## Customizing your Claude
  166. The system is shaped by a few Markdown files. See **[docs/customization.md](docs/customization.md)** for the full guide.
  167. The short version:
  168. | File | What it does | Who writes it |
  169. |------|-------------|---------------|
  170. | `~/.claude/CLAUDE.md` | Personality, preferences, rules — the brain | You |
  171. | `HEARTBEAT.md` | Heartbeat behavior + checklist | You |
  172. | `memory/bank/*.md` | Structured knowledge (preferences, experience, relationships) | You + Claude |
  173. | `MEMORY.md` | Auto-generated memory index | System |
  174. | `memory/YYYY-MM-DD.md` | Daily logs | System |
  175. ## Acknowledgements
  176. [imprint-memory](https://github.com/Qizhan7/imprint-memory) · [Anthropic](https://anthropic.com) · [Ollama](https://ollama.com) + [bge-m3](https://huggingface.co/BAAI/bge-m3)
  177. ## License
  178. [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 in

Free to use. If it’s helped, pass it on.