{"id":45358678,"url":"https://github.com/pitimon/c-memforge","last_synced_at":"2026-05-29T00:00:19.123Z","repository":{"id":336609302,"uuid":"1150378584","full_name":"pitimon/c-memforge","owner":"pitimon","description":"MemForge Client - Persistent semantic memory for Claude Code","archived":false,"fork":false,"pushed_at":"2026-05-27T15:22:25.000Z","size":213,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T15:27:39.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pitimon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-05T07:54:51.000Z","updated_at":"2026-05-27T15:23:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"31d756d0-a473-46e5-953e-d2e2c310565e","html_url":"https://github.com/pitimon/c-memforge","commit_stats":null,"previous_names":["pitimon/c-memforge"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/pitimon/c-memforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitimon%2Fc-memforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitimon%2Fc-memforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitimon%2Fc-memforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitimon%2Fc-memforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pitimon","download_url":"https://codeload.github.com/pitimon/c-memforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitimon%2Fc-memforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33630999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":[],"created_at":"2026-02-21T13:32:09.587Z","updated_at":"2026-05-29T00:00:18.893Z","avatar_url":"https://github.com/pitimon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MemForge Client\n\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n\n**Persistent semantic memory for Claude Code** — search, recall, and connect knowledge across sessions and projects.\n\n## What You Can Do\n\n- **Search memory** across all your past sessions — by keyword, concept, or semantic similarity\n- **Cross-project knowledge** — find related work from other projects automatically\n- **Team knowledge sharing** — access shared knowledge pool from team members\n- **Knowledge graph** — query entity relationships and triplet connections\n- **Automatic sync** — observations sync to the server in the background, no manual steps\n\n## Installation\n\n### Prerequisites\n\n1. **Bun runtime**: `curl -fsSL https://bun.sh/install | bash`\n2. **claude-mem plugin**: `/plugin marketplace add thedotmack/claude-mem`\n\n### Step 1: Add Marketplace + Install Plugin\n\nRun these commands in your **terminal** (not inside Claude Code):\n\n```bash\n# Add the marketplace source\nclaude plugin marketplace add pitimon/c-memforge\n\n# Install the plugin\nclaude plugin install memforge-client@pitimon-c-memforge\n```\n\n### Step 2: Configure API Key\n\nGet your API key at https://memclaude.thaicloud.ai/settings, then create the config:\n\n```bash\nmkdir -p ~/.memforge\ncat \u003e ~/.memforge/config.json \u003c\u003c 'EOF'\n{\n  \"apiKey\": \"your-api-key-here\",\n  \"serverUrl\": \"https://memclaude.thaicloud.ai\",\n  \"syncEnabled\": true,\n  \"pollInterval\": 2000,\n  \"role\": \"client\"\n}\nEOF\n```\n\n### Step 3: Restart Claude Code\n\nRestart to load the plugin. Verify with `mem_status` tool — should show connectivity OK.\n\n---\n\n## MCP Tools (27)\n\n### Search (start here)\n\n| Tool                  | When to Use                                               |\n| --------------------- | --------------------------------------------------------- |\n| `mem_semantic_search` | **Primary** — use FIRST. Supports hybrid/fts/vector modes |\n| `mem_temporal_query`  | Time-based search (\"yesterday\", \"last week\", dates)       |\n| `mem_hybrid_search`   | Dedicated hybrid (backward compat — use semantic_search)  |\n| `mem_vector_search`   | Pure semantic similarity                                  |\n| `mem_search`          | Keyword-only (FTS) with project/type filter               |\n\n### Retrieve\n\n| Tool                   | Purpose                                          |\n| ---------------------- | ------------------------------------------------ |\n| `mem_semantic_get`     | Get single observation by ID                     |\n| `mem_semantic_recent`  | Get recent observations                          |\n| `mem_timeline`         | Get context around an observation (before/after) |\n| `mem_get_observations` | Batch fetch multiple observations by IDs         |\n\n### Memory Curation\n\n| Tool                 | Purpose                                                              |\n| -------------------- | -------------------------------------------------------------------- |\n| `mem_pin`            | Pin observation — protect from decay/archival                        |\n| `mem_set_importance` | Override importance score (0-1)                                      |\n| `mem_set_event_date` | Set temporal event date for time-based queries                       |\n| `mem_set_status`     | Set lifecycle status (active/deprecated/superseded/applied/archived) |\n| `mem_contradict`     | Mark stale + create correction observation                           |\n| `mem_drift_check`    | Find oldest unverified observations                                  |\n\n### Knowledge Graph\n\n| Tool                 | Purpose                                      |\n| -------------------- | -------------------------------------------- |\n| `mem_entity_lookup`  | Find all triplets mentioning an entity       |\n| `mem_triplets_query` | Query subject-predicate-object relationships |\n\n### Cross-Project \u0026 Team\n\n| Tool                 | Purpose                                         |\n| -------------------- | ----------------------------------------------- |\n| `mem_cross_project`  | Find related observations from other projects   |\n| `mem_team_knowledge` | Search shared team knowledge pool               |\n| `mem_stable_context` | Get stable observation log (for prompt caching) |\n\n### SkillNet\n\n| Tool                 | Purpose                                    |\n| -------------------- | ------------------------------------------ |\n| `mem_skill_search`   | Search skills by query, category, or tags  |\n| `mem_skill_get`      | Get a specific skill with full details     |\n| `mem_skill_related`  | Find related skills via graph traversal    |\n| `mem_skill_create`   | Extract a reusable skill from observations |\n| `mem_skill_discover` | Browse the public skill catalog            |\n\n### Data \u0026 Workflow\n\n| Tool                   | Purpose                                           |\n| ---------------------- | ------------------------------------------------- |\n| `mem_ingest`           | Push observations to the server                   |\n| `mem_workflow_suggest` | Get workflow suggestions based on context         |\n| `mem_status`           | Check config, connectivity, auth, tier, and quota |\n\nAll tool responses include **workflow hints** (`suggested_next`) guiding you to the right follow-up tool.\n\n---\n\n## Tiers \u0026 Quotas\n\nYour API key is associated with a tier that determines available features:\n\n| Tier           | Observations | Search Modes          | Synthesis/day | Rate Limit |\n| -------------- | ------------ | --------------------- | ------------- | ---------- |\n| **Free**       | 5,000        | FTS only              | 10            | 60/min     |\n| **Pro**        | 100,000      | FTS + Vector + Hybrid | 200           | 300/min    |\n| **Team**       | Unlimited    | All + cross-user      | Unlimited     | 600/min    |\n| **Enterprise** | Unlimited    | All + SSO + audit     | Unlimited     | Custom     |\n\nRun `mem_status` to see your current tier and quota usage. The server endpoints `/api/auth/me`, `/api/account`, and `/api/user/me` all return tier and quota details.\n\n---\n\n## Configuration\n\nStored at `~/.memforge/config.json`:\n\n| Option         | Description            | Default                          |\n| -------------- | ---------------------- | -------------------------------- |\n| `apiKey`       | Your MemForge API key  | (required)                       |\n| `serverUrl`    | Server URL             | `https://memclaude.thaicloud.ai` |\n| `syncEnabled`  | Enable background sync | `true`                           |\n| `pollInterval` | Sync interval in ms    | `2000`                           |\n| `role`         | `client` or `admin`    | `client`                         |\n\nFor self-hosted servers, change `serverUrl` to your server URL.\n\n---\n\n## How It Works\n\n```\nclaude-mem (local)          memforge-client (this plugin)          MemForge Server\n━━━━━━━━━━━━━━━━           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━           ━━━━━━━━━━━━━━\nLLM creates structured  →  SyncPoller reads SQLite     →  POST /api/sync/push\nobservations in SQLite      every 2-10s (adaptive)         stores + embeds + extracts entities\n\n                            27 MCP tools  ←─────────────  Search, curation, graph, skills\n                            + workflow hints                + 15 background workers\n```\n\n- **claude-mem** creates structured observations via LLM (haiku) — this is the data source\n- **memforge-client** syncs observations to the server AND provides search tools\n- **MemForge Server** stores data in PostgreSQL + pgvector, provides search APIs\n\nSync runs in-process with the MCP server. No separate daemon or background process.\n\n---\n\n## Troubleshooting\n\n| Problem                        | Solution                                                                                            |\n| ------------------------------ | --------------------------------------------------------------------------------------------------- |\n| \"Remote search not configured\" | Check `~/.memforge/config.json` has valid `apiKey`                                                  |\n| \"Required: claude-mem plugin\"  | Install: `/plugin marketplace add thedotmack/claude-mem`                                            |\n| \"bun: command not found\"       | Install: `curl -fsSL https://bun.sh/install \\| bash`                                                |\n| SSH error on plugin install    | Use HTTPS: `claude plugin marketplace add pitimon/c-memforge`                                       |\n| Sync not working               | Run `mem_status` tool. Check `syncEnabled: true` in config                                          |\n| Slow search                    | Use `mem_search` (FTS) instead of vector. Add date filters. Lower `limit`                           |\n| MCP server won't start         | Missing dependencies — see [First-run dependency install](#first-run-dependency-install) below      |\n| Old observations not syncing   | Remove watermark file — see [Backfill existing observations](#backfill-existing-observations) below |\n| Claude Code hangs on startup   | claude-mem `smart-install.js` runs `bun install` — wait 30-60s or check network                     |\n| Old db-watcher zombie process  | See [Upgrading from v1.x](#upgrading-from-v1x) below                                                |\n\n### First-run dependency install\n\nAfter `claude plugin install`, the MCP server may fail to connect because dependencies aren't installed in the cache directory. Fix:\n\n```bash\n# Find the cache directory and install dependencies\ncd ~/.claude/plugins/cache/pitimon-c-memforge/memforge-client/*/\nbun install\n```\n\nThen reconnect: run `/mcp` in Claude Code and reconnect memforge, or restart Claude Code.\n\n### Backfill existing observations\n\nIf you installed c-memforge after using claude-mem for a while, your existing observations may not have synced. To backfill:\n\n```bash\n# Remove watermark — next startup will sync all observations from the beginning\nrm -f ~/.memforge/.sync-watermark.json\n```\n\nRestart Claude Code. The SyncPoller will log:\n\n```\n[SyncPoller] Fresh install — backfilling N existing observations\n```\n\nServer-side deduplication prevents duplicates, so this is safe to run anytime.\n\n### Verify sync is actually working\n\nIf you suspect the observation count on the MemForge UI is lower than it should be, run `mem_status` — it includes a **Pipeline Health** section that pinpoints which layer is failing. The numbers you see will reflect your own activity:\n\n```\n### Pipeline Health\n**Activity (last 24h):** N transcript file(s) modified\n**Captured (last 24h):** M obs in claude-mem.db (latest id=…)\n**Sync cursor:** obs #… (K unsynced)\n**Server (lifetime):** … obs accepted\n**Sync workers:** synced ok, 0 failed, 0 pending, circuit=closed\n\n✓ Healthy — all 4 layers aligned.\n```\n\nThe 4 layers form a pipeline. A gap between adjacent layers points at a specific failure mode:\n\n| Gap   | Symptom                                                   | Likely cause                                                           | Where to look                                                          |\n| ----- | --------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| **A** | transcripts \u003e 0 but `Captured` is 0 (or `\u003c\u003c` transcripts) | claude-mem hooks not running — observations are never produced locally | `~/.claude/settings.json` PostToolUse hook + `~/.claude-mem/logs/`     |\n| **B** | `unsynced` is large or `circuit=open`                     | sync poller is behind or server unreachable                            | sync-poller stderr; check connectivity in the same `mem_status` output |\n| **C** | `failed \u003e 0`                                              | server rejected uploads (quota, auth, malformed payload)               | tier quota above; API key validity; server logs                        |\n\nThis is the **most common silent-failure mode**: claude-mem hook misconfiguration produces no observations at all, yet `mem_status` connectivity/auth/sync all show GREEN. The Pipeline Health section is what makes Gap A visible.\n\nIf `Captured` keeps reporting 0 after Gap A is shown, re-check that `claude-mem` is installed and that `~/.claude-mem/claude-mem.db` exists and is being written to (mtime should advance during use).\n\n### Upgrading from v1.x\n\nv2.0+ moved sync into the MCP server process. If upgrading from v1.x, clean up legacy processes and files:\n\n```bash\n# Kill old daemon if still running\npkill -f db-watcher 2\u003e/dev/null\n\n# Remove old plugin cache (may spawn zombie db-watcher)\nrm -rf ~/.claude/plugins/cache/pitimon-c-memforge/\n\n# Remove legacy state files\nrm -f ~/.memforge/.sync-queue.json\nrm -f ~/.claude-mem/memforge-sync.pid ~/.claude-mem/memforge-sync.log\n```\n\nThen reinstall fresh:\n\n```bash\nclaude plugin uninstall memforge-client@pitimon-c-memforge\nclaude plugin marketplace add pitimon/c-memforge\nclaude plugin install memforge-client@pitimon-c-memforge\n```\n\n## Updating\n\n```bash\nclaude plugin update pitimon-c-memforge\n```\n\nConfig at `~/.memforge/config.json` is preserved. Restart Claude Code after updating.\n\n---\n\n## License\n\nAGPL-3.0 — See [LICENSE](LICENSE) for details.\n\n## Credits\n\n- **MemForge Server** by [@pitimon](https://github.com/pitimon)\n- **claude-mem Plugin** by [@thedotmack](https://github.com/thedotmack)\n\n## Development\n\nSee [MAINTENANCE.md](MAINTENANCE.md) for architecture details, release runbook, and development setup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitimon%2Fc-memforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpitimon%2Fc-memforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitimon%2Fc-memforge/lists"}