CogmemAi — Cognitive Memory for Claude Code

1<p align="center">
2  <img src="assets/hero.png" alt="CogmemAi — Why Claude Code Forgets Everything (And How to Fix It)" width="800">
3</p>
4 
5# CogmemAi — Cognitive Memory for Claude Code
6 
7**Claude Code forgets everything between sessions. CogmemAi fixes that.**
8 
9One command. Claude Code remembers your architecture, patterns, decisions, bugs, and preferences — permanently.
10 
11## Quick Start
12 
13```bash
14npx cogmemai-mcp setup
15```
16 
17That's it. The setup wizard verifies your API key, configures Claude Code, and you're ready. Start Claude Code by typing `claude` and your memories are ready.
18 
19Don't have an API key yet? Get one free at [hifriendbot.com/developer](https://hifriendbot.com/developer/).
20 
21## The Problem
22 
23Every time you start a new Claude Code session, you lose context. You re-explain your tech stack, your architecture decisions, your coding preferences. Claude Code's built-in memory is a 200-line flat file with no search, no structure, and no intelligence.
24 
25CogmemAi gives Claude Code a real memory system:
26 
27- **Semantic search** — finds relevant memories by meaning, not keywords
28- **Ai-powered extraction** — automatically identifies facts worth remembering from your conversations
29- **Smart deduplication** — detects duplicate and conflicting memories automatically
30- **Privacy controls** — auto-detects API keys, tokens, and secrets before storing
31- **Document ingestion** — feed in READMEs and docs to instantly build project context
32- **Project scoping** — memories tied to specific repos, plus global preferences that follow you everywhere
33- **Smart context** — blends importance, semantic relevance, and recency for better retrieval
34- **Auto-reload after compaction** — survives Claude Code context compaction automatically
35- **Zero setup** — no databases, no Docker, no Python, no vector stores
36 
37## Why Not Local Memory?
38 
39Every local memory solution has the same problems: database corruption, memory leaks, version conflicts, complex setup. [claude-mem](https://github.com/nicobailon/claude-mem) (13K+ stars) leaks 15GB+ of RAM. [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) released v10.0.0 marked "BROKEN."
40 
41CogmemAi runs extraction and search server-side. Your MCP server is a thin HTTP client — **zero local databases, zero RAM issues, zero crashes.**
42 
43## Compaction Recovery
44 
45When Claude Code compacts your context (auto or manual), conversation history gets compressed and context is lost. CogmemAi handles this automatically with two hooks:
46 
471. **PreCompact** — Before compaction, saves a session summary to the cloud
482. **UserPromptSubmit** — On your next message after compaction, detects the compaction, fetches your project context from the API, and injects it directly into the conversation
49 
50The result: seamless recovery. Claude responds with full context after compaction — no re-explaining, no manual prompting.
51 
52The `npx cogmemai-mcp setup` command installs both hooks automatically into `~/.claude/settings.json`. Hooks are session-specific — multiple terminals won't interfere with each other.
53 
54## CLI Commands
55 
56```bash
57npx cogmemai-mcp setup          # Interactive setup wizard
58npx cogmemai-mcp setup <key>    # Setup with API key
59npx cogmemai-mcp verify         # Test connection and show usage
60npx cogmemai-mcp --version      # Show installed version
61npx cogmemai-mcp help           # Show all commands
62```
63 
64## Manual Setup
65 
66If you prefer to configure manually instead of using `npx cogmemai-mcp setup`:
67 
68**Option A — Per project** (add `.mcp.json` to your project root):
69 
70```json
71{
72  "mcpServers": {
73    "cogmemai": {
74      "command": "cogmemai-mcp",
75      "env": {
76        "COGMEMAI_API_KEY": "cm_your_api_key_here"
77      }
78    }
79  }
80}
81```
82 
83**Option B — Global** (available in every project):
84 
85```bash
86claude mcp add cogmemai cogmemai-mcp -e COGMEMAI_API_KEY=cm_your_api_key_here --scope user
87```
88 
89## Works With
90 
91| Editor | Setup |
92|--------|-------|
93| **Claude Code** | `npx cogmemai-mcp setup` (automatic) |
94| **Cursor** | Add to `~/.cursor/mcp.json` |
95| **Windsurf** | Add to `~/.codeium/windsurf/mcp_config.json` |
96| **Cline** | VS Code settings → Cline MCP Servers |
97| **Continue** | Add to `~/.continue/config.yaml` |
98 
99All editors use the same config format — see the [setup guides](https://hifriendbot.com/developer/) for each editor.
100 
101## Tools
102 
103CogmemAi provides 12 tools that Claude Code uses automatically:
104 
105| Tool | Description |
106|------|-------------|
107| `save_memory` | Store a fact explicitly (architecture decision, preference, etc.) |
108| `recall_memories` | Search memories using natural language (semantic search) |
109| `extract_memories` | Ai extracts facts from a conversation exchange automatically |
110| `get_project_context` | Load top memories at session start (with optional context for smart ranking) |
111| `list_memories` | Browse memories with filters (paginated) |
112| `update_memory` | Update a memory's content, importance, or scope |
113| `delete_memory` | Permanently delete a memory |
114| `get_usage` | Check your usage stats and tier info |
115| `export_memories` | Export all memories as JSON for backup or transfer |
116| `import_memories` | Bulk import memories from a JSON array |
117| `ingest_document` | Feed in a document (README, API docs) to auto-extract memories |
118| `save_session_summary` | Save a summary of what was accomplished in this session |
119 
120## SDKs
121 
122Build your own integrations with the CogmemAi API:
123 
124- **JavaScript/TypeScript:** `npm install cogmemai-sdk` — [npm](https://www.npmjs.com/package/cogmemai-sdk) · [GitHub](https://github.com/hifriendbot/cogmemai-sdk)
125- **Python:** `pip install cogmemai` — [PyPI](https://pypi.org/project/cogmemai/) · [GitHub](https://github.com/hifriendbot/cogmemai-python)
126 
127## Memory Types
128 
129Memories are categorized for better organization and retrieval:
130 
131- **identity** — Who you are, your role, team
132- **preference** — Coding style, tool choices, conventions
133- **architecture** — System design, tech stack, file structure
134- **decision** — Why you chose X over Y
135- **bug** — Known issues, fixes, workarounds
136- **dependency** — Version constraints, package notes
137- **pattern** — Reusable patterns, conventions
138- **context** — General project context
139 
140## Scoping
141 
142- **Project memories** — Architecture, decisions, bugs specific to one repo. Auto-detected from `git remote`.
143- **Global memories** — Your coding preferences, identity, tool choices. Available in every project.
144 
145## Pricing
146 
147| | Free | Pro | Team | Enterprise |
148|---|---|---|---|---|
149| **Price** | $0 | $14.99/mo | $39.99/mo | $99.99/mo |
150| **Memories** | 1,000 | 2,000 | 10,000 | 50,000 |
151| **Extractions/mo** | 500 | 2,000 | 5,000 | 20,000 |
152| **Projects** | 5 | 20 | 50 | 200 |
153 
154Start free. Upgrade when you need more.
155 
156## Privacy & Security
157 
158- **No source code leaves your machine.** We store extracted facts (short sentences), never raw code.
159- **API keys hashed** with SHA-256 (irreversible) server-side.
160- **All traffic over HTTPS.**
161- **No model training** on your data. Ever.
162- **Delete everything** instantly via dashboard or MCP tool.
163- **No cross-user data sharing.**
164 
165Read our full [privacy policy](https://hifriendbot.com/privacy-policy/).
166 
167## Environment Variables
168 
169| Variable | Required | Description |
170|----------|----------|-------------|
171| `COGMEMAI_API_KEY` | Yes | Your API key (starts with `cm_`) |
172| `COGMEMAI_API_URL` | No | Custom API URL (default: hifriendbot.com) |
173 
174## How It Works
175 
176```
177Your Terminal                          CogmemAi Cloud
178┌──────────────┐                     ┌─────────────────────┐
179│ Claude Code  │                     │ 3-Layer Memory      │
180│              │                     │                     │
181│ cogmemai-mcp │ ──── HTTPS ────►    │ 1. Ai Extraction    │
182│ (MCP Server) │ ◄──── JSON ────    │ 2. Semantic Search  │
183│              │                     │ 3. Time-Aware Rank  │
184└──────────────┘                     └─────────────────────┘
185```
186 
1871. **Extraction** — When Claude Code works on your project, CogmemAi's Ai identifies important facts (architecture decisions, preferences, bugs) and stores them.
1882. **Embedding** — Each memory gets a semantic embedding vector for meaning-based search.
1893. **Surfacing** — When you start a new session, relevant memories are surfaced by meaning, importance, and recency.
190 
191## Support
192 
193- Issues: [GitHub Issues](https://github.com/hifriendbot/cogmemai-mcp/issues)
194- Docs: [hifriendbot.com/developer](https://hifriendbot.com/developer/)
195 
196## License
197 
198MIT — see [LICENSE](./LICENSE)
199 
200---
201 
202Built by [HiFriendbot](https://hifriendbot.com) — Better Friends, Better Memories, Better Ai.
203