{"id":45310849,"url":"https://github.com/zelinewang/claudemem","last_synced_at":"2026-04-23T02:01:20.151Z","repository":{"id":339699501,"uuid":"1163029954","full_name":"zelinewang/claudemem","owner":"zelinewang","description":"Unified agent memory: knowledge notes + session summaries. Go CLI with FTS5 search, zero network. Claude Code skill.","archived":false,"fork":false,"pushed_at":"2026-04-22T02:13:25.000Z","size":333,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-22T04:27:55.928Z","etag":null,"topics":["ai-agent","claude-code","coding-agent","cursor","developer-tools","fts5","gemini","go","memory","persistent-memory","skills","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zelinewang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T01:48:58.000Z","updated_at":"2026-04-22T02:13:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zelinewang/claudemem","commit_stats":null,"previous_names":["zelinewang/claudemem"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zelinewang/claudemem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zelinewang%2Fclaudemem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zelinewang%2Fclaudemem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zelinewang%2Fclaudemem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zelinewang%2Fclaudemem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zelinewang","download_url":"https://codeload.github.com/zelinewang/claudemem/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zelinewang%2Fclaudemem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"online","status_checked_at":"2026-04-23T02:00:06.710Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","coding-agent","cursor","developer-tools","fts5","gemini","go","memory","persistent-memory","skills","sqlite"],"created_at":"2026-02-21T07:11:08.782Z","updated_at":"2026-04-23T02:01:20.144Z","avatar_url":"https://github.com/zelinewang.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claudemem\n\nPersistent memory for AI coding agents. Notes and session summaries that survive across conversations — with bidirectional cross-referencing.\n\n## Install\n\n```bash\nnpx skills add zelinewang/claudemem\n```\n\nThat's it. Next time you start Claude Code (or Cursor, Gemini CLI, etc.), it just works.\n\n### Upgrade\n\n```bash\nnpx skills add zelinewang/claudemem -y -g\n```\n\nSame command as install. Overwrites with the latest version. Your saved data (`~/.claudemem/`) is never touched.\n\n## How It Works\n\n**claudemem remembers things for you across conversations.**\n\nDuring your work, it silently saves important context — API specs, decisions, quirks, resolved bugs. When you start a new task, it searches past knowledge automatically.\n\nYou can also talk to it naturally:\n\n| Say this | What happens |\n|----------|-------------|\n| \"remember this\" | Saves the current info as a note |\n| \"what do you remember about TikTok\" | Searches past notes |\n| \"wrap up\" | Saves detailed session report + extracts notes |\n| \"what did we do last time\" | Shows recent sessions |\n\nOr use slash commands: `/wrapup`, `/recall [topic]`\n\n## What Gets Saved\n\n```\n~/.claudemem/\n├── notes/          ← knowledge fragments (markdown)\n├── sessions/       ← work reports with cross-links (markdown)\n└── .index/         ← search index (auto-rebuilt)\n```\n\nEverything is plain Markdown with YAML frontmatter. Human-readable, git-friendly, portable.\n\n## CLI Quick Reference\n\n```bash\n# Notes (knowledge fragments)\nclaudemem note add \u003ccategory\u003e --title \"...\" --content \"...\" [--tags \"...\"] [--session-id \"...\"]\nclaudemem note search \"query\" [--in category] [--tag tags]\nclaudemem note list [category]\nclaudemem note get \u003cid-or-prefix\u003e\nclaudemem note append \u003cid\u003e \"additional content\"\nclaudemem note update \u003cid\u003e --title \"...\" --content \"...\" --tags \"...\"\nclaudemem note delete \u003cid\u003e\nclaudemem note categories\nclaudemem note tags\n\n# Sessions (work reports)\nclaudemem session save --title \"...\" --branch \"...\" --project \"...\" --session-id \"...\" \\\n  [--related-notes \"id:title:category,...\"] [--content \"...\"]\nclaudemem session list [--last N] [--branch X] [--date-range 7d]\nclaudemem session search \"query\" [--branch X]\nclaudemem session get \u003cid-or-prefix\u003e\n\n# Search everything\nclaudemem search \"query\" [--type note|session] [--limit N]\n\n# Embedding backend (pick one; no silent fallback)\nclaudemem setup                              # interactive wizard: Local / Gemini / Voyage / OpenAI / TF-IDF\nclaudemem health                             # I1-I3 parity check (markdown ↔ FTS ↔ vectors, \u003c100ms)\nclaudemem health --deep                      # also I4/I5 (orphans, config match)\nclaudemem repair                             # fix drift detected by health (interactive)\n\n# Cross-machine sync (markdown-only via git)\nclaudemem sync init \u003cremote-url\u003e             # git init ~/.claudemem with remote\nclaudemem sync push                          # commit + push notes/sessions\nclaudemem sync pull                          # pull + rebuild FTS + embed missing vectors\nclaudemem sync status                        # git status + index health\n\n# Utilities\nclaudemem stats\nclaudemem verify\nclaudemem repair\nclaudemem config set/get/list/delete \u003ckey\u003e [value]\nclaudemem export backup.tar.gz\nclaudemem import backup.tar.gz\n```\n\nAdd `--format json` to any command for structured output.\n\n## Setup — Pick Your Search Backend\n\nSemantic search uses an embedding model. Pick it explicitly — claudemem never\nfalls back silently to a worse backend behind your back.\n\n```bash\nclaudemem setup\n```\n\nThe wizard walks through:\n\n| Option | Where it runs | Cost | Chinese | When to pick |\n|---|---|---|---|---|\n| **Local — Ollama** | Your machine | Free | qwen3 ✅ / nomic weaker | Daily use, offline, airgapped |\n| **Cloud — Gemini** | Google | $0.15/M tokens (≈$0.50/mo for 3K notes) | ✅ 100+ langs | Best quality, you already have a key |\n| **Cloud — Voyage** | Voyage AI | $0.02/M, 200M free tokens | ✅ | Budget pick, effectively free |\n| **Cloud — OpenAI** | OpenAI | $0.02/M (3-small) | ⚠️ English-heavy | You already pay OpenAI for other things |\n| **TF-IDF** | Your machine | Free | OK | No daemon, no keys, keyword-ish similarity |\n\nAPI keys are always read from environment variables (`GEMINI_API_KEY`,\n`VOYAGE_API_KEY`, `OPENAI_API_KEY`) — claudemem refuses to store them in\n`config.json`. Only the env var **name** is recorded, so configs are safe\nto commit + sync across machines.\n\nManual equivalent (for scripts):\n\n```bash\nclaudemem config set embedding.backend gemini\nclaudemem config set embedding.model gemini-embedding-001\nclaudemem config set embedding.dimensions 768\nclaudemem config set embedding.api_key_env GEMINI_API_KEY\nclaudemem reindex --vectors\n```\n\n### When the backend is down\n\nclaudemem never degrades silently. If the configured backend is unreachable:\n\n- **Non-interactive shells / CI**: error with recovery instructions + exit 1.\n- **Interactive terminals**: prompt offering retry / FTS-only-this-query / run setup.\n\nUse `claudemem search \"...\" --fts-only` to skip semantic for one query\nwhen you know the backend is down.\n\n## Cross-Machine Memory\n\nMemory can follow you between machines (web_dev ↔ MacBook, etc.) via a\nprivate git repo.\n\n```bash\n# once, per user (HTTPS recommended — works with gh auth / keychain)\nclaudemem sync init https://github.com/YOU/claudemem-memory.git\n\n# after work\nclaudemem sync push\n\n# on another machine, first time (existing notes are auto-committed as baseline)\nclaudemem sync init https://github.com/YOU/claudemem-memory.git\nclaudemem sync pull\n```\n\nOnly markdown travels over the wire — SQLite index and config stay\nper-machine. Each machine embeds under ITS configured backend, so\na cloud-Gemini laptop and a local-Ollama workstation can share the\nsame corpus with zero backend coupling.\n\nSee [docs/HOOK_INTEGRATION.md](docs/HOOK_INTEGRATION.md) for Claude Code\nhook integration (auto-pull on SessionStart, auto-push on SessionEnd).\n\n## Recommended: Auto Wrap-Up\n\nWant every session saved automatically? Add this to your `~/.claude/CLAUDE.md`:\n\n```markdown\n### Session Memory — Auto Wrap-Up\n- Before ending any conversation, automatically execute `/wrapup` to save knowledge and session summary.\n- Do not ask permission — just do it as the final action.\n```\n\n## Key Features\n\n- **Cross-referencing** — notes link to sessions, sessions link to notes. Trace any knowledge back to its source\n- **Custom sections preserved** — architecture diagrams, performance tables, file lists — nothing silently dropped\n- **Smart dedup** — notes merge by topic; sessions stay separate by conversation (session_id-based)\n- **FTS5 search** — full-text search across all notes and sessions in \u003c10ms, with automatic query sanitization (hyphens, quotes, special chars handled safely)\n- **Hybrid search** — FTS5 keyword search + semantic vector search (Gemini / Voyage / OpenAI / Ollama / TF-IDF). Score fusion tuned for keyword-heavy memory queries\n- **Opt-in network** — default is zero-network (TF-IDF or offline). Cloud embedding backends are explicit per-machine choices via `claudemem setup`; API keys come from env vars only, never stored in config\n- **Portable** — export/import as tar.gz, move between machines\n- **440+ tests** — 331 unit (82% coverage), 23 E2E, 82 black-box feature tests across 7 levels\n\n## For Developers\n\n### Build from source\n\n```bash\ngit clone https://github.com/zelinewang/claudemem.git\ncd claudemem\nmake build          # Build binary\nmake install        # Install to ~/.local/bin/\n```\n\n### Run tests\n\n```bash\nmake test           # Quick smoke test (5 operations)\nmake e2e-test       # 23 end-to-end CLI tests\nmake feature-test   # 82 black-box feature tests (7 levels)\nmake test-all       # All tests: unit + smoke + e2e + feature\n\n# Go unit tests directly\ngo test ./... -v    # 331 unit tests, 82% coverage\n```\n\n### Test coverage\n\n| Layer | Tests | What it covers |\n|-------|-------|---------------|\n| Go unit tests | 331 | Models, validation, markdown, storage, dedup, search, cross-ref, integrity, faceted search, timestamp parsing, FTS5 sanitization, session merge, vector store, migration |\n| Smoke test | 5 | Basic note/session/search/stats |\n| E2E CLI | 23 | Full CLI flag testing, JSON output, metadata, cross-referencing, capture, graph |\n| Feature tests | 82 | 7 levels: CRUD, search, dedup, cross-ref, edge cases, boundaries, data lifecycle |\n| **Total** | **441** | **82.2% statement coverage** on core storage package |\n\nAll tests use temp directories — zero local environment dependencies, fully replicatable.\n\n## Architecture\n\nNotes and sessions have fundamentally different dedup strategies:\n\n| | Notes | Sessions |\n|---|---|---|\n| **Purpose** | Knowledge fragments | Work reports |\n| **Dedup key** | Same title + category | Same session_id |\n| **Merge behavior** | Append content | Append all sections |\n| **Cross-link** | `metadata.session_id` | `## Related Notes` |\n\nThis ensures knowledge accumulates naturally while different conversations stay separate.\n\n## Security\n\nskills.sh shows \"High Risk\" / \"Critical Risk\" badges — this is normal for **any skill that runs CLI commands**. Here's what's actually going on:\n\n| Scanner | Flag | Why | Real risk |\n|---------|------|-----|-----------|\n| Gen | High | Skill uses Bash to run `claudemem` | All useful skills need this |\n| Socket | 1 alert | `install.sh` downloads binary via curl | Standard Go distribution |\n| Snyk | Critical | `modernc.org/sqlite` (C-to-Go transpile) has CVEs | Industry-standard SQLite lib |\n\n**What claudemem actually does**: zero network by default (TF-IDF or offline Ollama); cloud embedding backends are opt-in per-machine via `claudemem setup` with API keys from env vars only. Parameterized SQL queries, FTS5 query sanitization, path traversal protection, 441 tests passing (82% coverage). Full source: ~11,400 lines of Go, fully auditable.\n\n## Tell a Friend\n\n\u003e Install persistent memory for Claude Code in 10 seconds:\n\u003e ```\n\u003e npx skills add zelinewang/claudemem\n\u003e ```\n\u003e Now say \"remember this\" or \"wrap up\" — it just works.\n\n## License\n\nMIT\n\n## References\n\n- [braindump](https://github.com/MohGanji/braindump) — Go-based persistent notes for AI agents\n- [claude-done](https://github.com/Genuifx/claude-done) — Session summary saving for Claude Code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzelinewang%2Fclaudemem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzelinewang%2Fclaudemem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzelinewang%2Fclaudemem/lists"}