specmem-hardwicksoftware 3.7.21 → 3.7.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +0 -0
- package/README.md +182 -388
- package/claude-hooks/specmem/sockets/session-start.lock +1 -0
- package/commands/specmem-changes.md +0 -0
- package/commands/specmem-code.md +0 -0
- package/commands/specmem-configteammembercomms.md +0 -0
- package/commands/specmem-find.md +0 -0
- package/commands/specmem-pointers.md +0 -0
- package/commands/specmem-remember.md +0 -0
- package/commands/specmem-service.md +0 -0
- package/commands/specmem-stats.md +0 -0
- package/commands/specmem-team-member.md +0 -0
- package/commands/specmem.md +0 -0
- package/embedding-sandbox/specmem/sockets/claude-input-state.json +1 -0
- package/embedding-sandbox/specmem/sockets/embedding-death-reason.txt +3 -0
- package/package.json +19 -3
- package/scripts/specmem/sockets/session-start.lock +1 -0
- package/specmem.env +0 -0
package/LICENSE.md
CHANGED
|
File without changes
|
package/README.md
CHANGED
|
@@ -10,116 +10,97 @@
|
|
|
10
10
|
<br/>
|
|
11
11
|
<br/>
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
[](https://www.npmjs.com/package/specmem-hardwicksoftware)
|
|
15
|
+
[](#whats-new-in-v37)
|
|
16
|
+
[](./LICENSE.md)
|
|
17
|
+
|
|
18
|
+
<!-- Tech Stack Badges -->
|
|
19
|
+
[](#features)
|
|
20
|
+
[](#architecture)
|
|
21
|
+
[](#platform-requirements)
|
|
22
|
+
[](#architecture)
|
|
23
|
+
[](#architecture)
|
|
24
|
+
|
|
25
|
+
<!-- Feature Badges -->
|
|
26
|
+
[](#the-embedding-server)
|
|
27
|
+
[](#the-embedding-server)
|
|
28
|
+
[](#multi-agent-team-coordination) [](#multi-agent-team-coordination)
|
|
29
|
+
[](#platform-requirements)
|
|
30
|
+
|
|
31
|
+
<!-- Language Support Badges -->
|
|
32
|
+
[](#language-support)
|
|
33
|
+
[](#language-support)
|
|
34
|
+
[](#language-support)
|
|
35
|
+
[](#language-support)
|
|
36
|
+
[](#language-support)
|
|
37
|
+
[](#language-support)
|
|
38
|
+
[](#language-support)
|
|
39
|
+
[](#language-support)
|
|
40
|
+
[](#language-support)
|
|
41
|
+
|
|
42
|
+
<br/>
|
|
17
43
|
|
|
18
44
|
**Persistent memory for your coding sessions. Your conversations don't vanish. Your context sticks around.**
|
|
19
45
|
|
|
20
|
-
|
|
46
|
+
<br/>
|
|
47
|
+
|
|
48
|
+
[The Problem](#the-problem) · [Competitors](#-why-not-use-something-else) · [Quick Start](#-quick-start) · [Why Root?](#-why-root) · [Features](#-features) · [Architecture](#-architecture) · [MCP Tools](#-mcp-tools)
|
|
21
49
|
|
|
22
50
|
</div>
|
|
23
51
|
|
|
24
52
|
---
|
|
25
53
|
|
|
26
|
-
##
|
|
54
|
+
## The Problem
|
|
27
55
|
|
|
28
56
|
<div align="center">
|
|
29
|
-
|
|
30
|
-
<!-- Training Prohibited Notice -->
|
|
31
57
|
<picture>
|
|
32
|
-
<
|
|
33
|
-
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-training-prohibited.svg">
|
|
34
|
-
<img alt="TRAINING PROHIBITED" src="./svg-sections/notice-training-prohibited.svg" width="800">
|
|
58
|
+
<img alt="The Problem" src="./svg-sections/readme-the-problem.svg" width="800">
|
|
35
59
|
</picture>
|
|
60
|
+
</div>
|
|
36
61
|
|
|
37
|
-
|
|
62
|
+
---
|
|
38
63
|
|
|
39
|
-
|
|
64
|
+
## 🔥 Why Not Use Something Else?
|
|
65
|
+
|
|
66
|
+
<div align="center">
|
|
40
67
|
<picture>
|
|
41
|
-
<
|
|
42
|
-
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-ip-protected.svg">
|
|
43
|
-
<img alt="Intellectual Property Protected" src="./svg-sections/notice-ip-protected.svg" width="700">
|
|
68
|
+
<img alt="Competitor Comparison" src="./svg-sections/readme-competitor-roast.svg" width="800">
|
|
44
69
|
</picture>
|
|
45
|
-
|
|
46
70
|
</div>
|
|
47
71
|
|
|
48
|
-
### Anthropic / Claude Developers: Your Own ToS Applies
|
|
49
|
-
|
|
50
|
-
**Anthropic's published Terms of Service state:**
|
|
51
|
-
|
|
52
|
-
> "If you decide to turn off the model training setting, **we will not use any new chats and coding sessions you have with Claude for future model training.**"
|
|
53
|
-
>
|
|
54
|
-
> "These updates apply to users on our **Claude Free, Pro, and Max plans, including when they use Claude Code** from accounts associated with those plans."
|
|
55
|
-
|
|
56
|
-
**Source:** [Anthropic Consumer Terms Update](https://www.anthropic.com/news/updates-to-our-consumer-terms)
|
|
57
|
-
|
|
58
|
-
**This project's "Help improve Claude" setting is DISABLED.**
|
|
59
|
-
|
|
60
|
-
Under Anthropic's stated policy:
|
|
61
|
-
- Our chats and coding sessions **shall not** be used for model training
|
|
62
|
-
- We retain the 30-day deletion policy, not 5-year retention
|
|
63
|
-
- Our code, architecture, and implementations are **not authorized** for training
|
|
64
|
-
|
|
65
|
-
<details>
|
|
66
|
-
<summary><strong>View Screenshot Evidence (January 30, 2026)</strong></summary>
|
|
67
|
-
|
|
68
72
|
<br/>
|
|
69
73
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
</details>
|
|
75
|
-
|
|
76
|
-
---
|
|
77
|
-
|
|
78
|
-
## ⚡ Pre-Release Status
|
|
79
|
-
|
|
80
74
|
<div align="center">
|
|
81
|
-
|
|
82
|
-
<!-- License Pre-Release Notice -->
|
|
83
75
|
<picture>
|
|
84
|
-
<
|
|
85
|
-
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-license-prerelease.svg">
|
|
86
|
-
<img alt="LICENSE NOT GRANT - Pre-Release" src="./svg-sections/notice-license-prerelease.svg" width="800">
|
|
76
|
+
<img alt="MCP Tool Comparison" src="./svg-sections/readme-tool-comparison.svg" width="600">
|
|
87
77
|
</picture>
|
|
88
|
-
|
|
89
78
|
</div>
|
|
90
79
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
## The Problem
|
|
94
|
-
|
|
95
|
-
Every Claude session starts fresh. You explain your auth system. Again. Your database schema. Again. That bug you fixed last week. Again.
|
|
80
|
+
<br/>
|
|
96
81
|
|
|
97
|
-
|
|
98
|
-
Before SpecMem: With SpecMem:
|
|
99
|
-
+----------------------------+ +----------------------------+
|
|
100
|
-
| "Hey Claude, remember the | | "Fix the auth bug" |
|
|
101
|
-
| auth module uses JWT with | | |
|
|
102
|
-
| refresh tokens and the | | Claude already knows: |
|
|
103
|
-
| edge case where expired | | - Your auth architecture |
|
|
104
|
-
| tokens need to..." | | - The JWT refresh flow |
|
|
105
|
-
| | | - Past bugs you fixed |
|
|
106
|
-
| [500 tokens of context] | | - Your code patterns |
|
|
107
|
-
+----------------------------+ +----------------------------+
|
|
108
|
-
```
|
|
82
|
+
<div align="center">
|
|
109
83
|
|
|
110
|
-
|
|
84
|
+
| Feature | <img src="https://img.shields.io/badge/-SpecMem-00bfff?style=flat-square" alt="SpecMem"/> | <img src="https://img.shields.io/badge/-claude--mem-ff6b6b?style=flat-square" alt="claude-mem"/> | Giga AI | Cursor | Continue | Cody | mem0 |
|
|
85
|
+
|---------|:-------:|:----------:|:-------:|:------:|:--------:|:----:|:----:|
|
|
86
|
+
| **Semantic Search** | `pgvector` | ChromaDB | Cloud | Limited | No | Limited | Yes |
|
|
87
|
+
| **Per-Project Isolation** | **Yes** | No | No | No | No | No | No |
|
|
88
|
+
| **Local Embeddings** | **Free** | Cloud API$ | No | Cloud | Cloud | Cloud | Cloud |
|
|
89
|
+
| **Multi-Agent** | **Unlimited Swarms** | No | No | No | No | No | No |
|
|
90
|
+
| **Session Memory** | **Auto** | Manual | No | Manual | No | No | Manual |
|
|
91
|
+
| **Code Tracebacks** | **Yes** | No | No | No | Limited | Yes | No |
|
|
92
|
+
| **Codebase Indexing** | **Full** | No | No | Partial | No | Yes | No |
|
|
93
|
+
| **Self-Hosted** | **Yes** | Partial | No | No | Partial | No | Yes |
|
|
94
|
+
| **MCP Native** | **Yes** | Yes | No | No | No | No | No |
|
|
95
|
+
| **Code Stays Local** | **Yes** | No | No | No | No | No | No |
|
|
96
|
+
| **MCP Tools** | **74+** | 4 | 0 | 0 | 0 | 0 | 0 |
|
|
97
|
+
| **Language Extractors** | **14** | 0 | 0 | 0 | 0 | 0 | 0 |
|
|
111
98
|
|
|
112
|
-
|
|
113
|
-
|---------------------|------------------|
|
|
114
|
-
| Static - doesn't update as code changes | **File watcher** auto-updates on every save |
|
|
115
|
-
| Keyword search only | **Semantic search** finds by meaning |
|
|
116
|
-
| One monolithic file | **Structured memories** with types, tags, importance |
|
|
117
|
-
| Cross-project pollution | **Per-project isolation** with separate schemas |
|
|
118
|
-
| Manual maintenance | **Auto-extraction** from your Claude sessions |
|
|
99
|
+
</div>
|
|
119
100
|
|
|
120
101
|
---
|
|
121
102
|
|
|
122
|
-
## Quick Start
|
|
103
|
+
## ⚡ Quick Start
|
|
123
104
|
|
|
124
105
|
<div align="center">
|
|
125
106
|
<picture>
|
|
@@ -127,297 +108,44 @@ Before SpecMem: With SpecMem:
|
|
|
127
108
|
</picture>
|
|
128
109
|
</div>
|
|
129
110
|
|
|
130
|
-
<br/>
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
# 1. Install (requires root — see "Why Root?" section below)
|
|
134
|
-
sudo npm install -g specmem-hardwicksoftware
|
|
135
|
-
|
|
136
|
-
# 2. First-time setup (downloads embedding models, sets up PostgreSQL)
|
|
137
|
-
specmem setup
|
|
138
|
-
|
|
139
|
-
# 3. Initialize in your project
|
|
140
|
-
cd /path/to/your/project
|
|
141
|
-
specmem init
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
**That's it.** Claude now has memory. From now on, just run `specmem init` instead of `claude` — it's a better startup anyway since it ensures all services are running before Claude connects.
|
|
145
|
-
|
|
146
|
-
Also check out `npm install -g claudefix` — it's a companion package that fixes common Claude Code issues. Both packages work great together but don't require each other.
|
|
147
|
-
|
|
148
|
-
### Test It Works
|
|
149
|
-
|
|
150
|
-
```bash
|
|
151
|
-
claude
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Ask Claude: **"What do you remember about this project?"**
|
|
155
|
-
|
|
156
|
-
If it's working, Claude will mention SpecMem and show indexed files.
|
|
157
|
-
|
|
158
|
-
### Check Status
|
|
159
|
-
|
|
160
|
-
```bash
|
|
161
|
-
specmem status
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
**Expected output:**
|
|
165
|
-
```
|
|
166
|
-
PostgreSQL Running (port 5432)
|
|
167
|
-
Embedding Running (Docker)
|
|
168
|
-
File Watcher Active (monitoring 1,234 files)
|
|
169
|
-
|
|
170
|
-
Memory Stats: 156 memories, 89 code files indexed
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
---
|
|
174
|
-
|
|
175
|
-
## Why Root?
|
|
176
|
-
|
|
177
|
-
Yeah, we know — nobody likes running stuff as root. We're actively working on removing this requirement (migrating to Bun, reworking permissions). But here's why it's there right now, and why we aren't apologizing for it yet.
|
|
178
|
-
|
|
179
|
-
SpecMem isn't some little npm package you toss into a project folder and forget about. It's a full system-level tool that does a lot under the hood, and most of that stuff can't happen without elevated permissions. Here's the real breakdown:
|
|
180
|
-
|
|
181
|
-
- **System-wide hooks** get dropped into `~/.claude/hooks/` — these intercept and augment every tool call in real-time. They aren't project-scoped, they're user-scoped, and writing to those directories from a global install needs elevated permissions on most Linux setups.
|
|
182
|
-
- **Docker container management** — SpecMem spins up PostgreSQL with pgvector in Docker. It creates containers, manages volumes, handles networking. Docker's socket (`/var/run/docker.sock`) typically needs root or docker group membership. We don't assume you've set up the docker group.
|
|
183
|
-
- **Global npm directories** — installing to `/usr/local/lib/node_modules/` and linking binaries to `/usr/local/bin/` means writing to system paths. That's just how global npm packages work on Linux. Nothing we can do about that one.
|
|
184
|
-
- **Screen sessions for background services** — the embedding server, file watcher, and MCP server all run in detached screen sessions. Managing those system-wide needs the right permissions.
|
|
185
|
-
- **PostgreSQL database setup** — first-run creates the database, enables pgvector, runs migrations, sets up per-project schemas. It's touching system-level database configs that a regular user can't write to.
|
|
186
|
-
- **File watching across your entire codebase** — chokidar watches thousands of files and needs access to whatever directories you're working in. Some of those directories have restrictive permissions.
|
|
187
|
-
|
|
188
|
-
There's also a practical reason we haven't rushed to remove it: **root requirement means you own your machine.** This isn't software for corporate laptops where some IT department controls what you can install. If you can't run `sudo npm install -g`, you probably don't own the box, and we've had issues with companies using SpecMem without proper licensing. The root requirement acts as a natural filter — it keeps usage to power users and developers who actually control their own systems. Companies that want to deploy this on managed infrastructure need to talk to us about commercial licensing first.
|
|
189
|
-
|
|
190
|
-
That said, we're not keeping this forever. The Bun migration is in progress and one of the goals is dropping the root requirement entirely. When that lands, you'll be able to run SpecMem as a regular user with Docker handled separately. But for now, if you want semantic search with vector embeddings, code memorization across sessions, 60% token compression, multi-agent team coordination, and a local embedding server that doesn't phone home — all of that runs as system services, and system services need root. There's no way around it with the current architecture.
|
|
191
|
-
|
|
192
111
|
---
|
|
193
112
|
|
|
194
|
-
##
|
|
113
|
+
## 🔐 Why Root?
|
|
195
114
|
|
|
196
115
|
<div align="center">
|
|
197
116
|
<picture>
|
|
198
|
-
<img alt="
|
|
117
|
+
<img alt="Why Root?" src="./svg-sections/readme-why-root.svg" width="800">
|
|
199
118
|
</picture>
|
|
200
119
|
</div>
|
|
201
120
|
|
|
202
|
-
<br/>
|
|
203
|
-
|
|
204
|
-
### Semantic Search That Actually Works
|
|
205
|
-
|
|
206
|
-
```
|
|
207
|
-
You type: "that function that handles rate limiting for the API"
|
|
208
|
-
|
|
209
|
-
SpecMem finds: rateLimiter(), handleThrottle(), apiQuotaManager()
|
|
210
|
-
+ related conversation context where you discussed them
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
Traditional search needs exact function names. SpecMem understands what you're looking for.
|
|
214
|
-
|
|
215
|
-
### Per-Project Isolation
|
|
216
|
-
|
|
217
|
-
Run 5 different projects simultaneously. Each gets:
|
|
218
|
-
|
|
219
|
-
| Component | Isolation |
|
|
220
|
-
|-----------|-----------|
|
|
221
|
-
| Database | Separate PostgreSQL schema (`specmem_{hash}`) |
|
|
222
|
-
| Embeddings | Dedicated embedding service per project |
|
|
223
|
-
| Sockets | Project-specific Unix sockets |
|
|
224
|
-
| Memories | No cross-contamination between projects |
|
|
225
|
-
|
|
226
|
-
### Code Pointers with Tracebacks
|
|
227
|
-
|
|
228
|
-
```javascript
|
|
229
|
-
find_code_pointers({ query: "authentication middleware" })
|
|
230
|
-
|
|
231
|
-
// Returns:
|
|
232
|
-
// authMiddleware() @ src/middleware/auth.ts:45
|
|
233
|
-
// Called by: router.use() @ src/routes/api.ts:12
|
|
234
|
-
// Calls: verifyToken() @ src/utils/jwt.ts:23
|
|
235
|
-
// Related memory: "Added rate limiting to auth middleware - Jan 15"
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
### Multi-Agent Coordination
|
|
239
|
-
|
|
240
|
-
```
|
|
241
|
-
Deploy research agent --+
|
|
242
|
-
Deploy frontend agent --+--> Team channel --> Coordinated output
|
|
243
|
-
Deploy backend agent --+
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Spawn specialized agents that:
|
|
247
|
-
- Claim files to avoid conflicts
|
|
248
|
-
- Share findings through team messages
|
|
249
|
-
- Request and provide help to each other
|
|
250
|
-
|
|
251
121
|
---
|
|
252
122
|
|
|
253
|
-
##
|
|
123
|
+
## ✨ Features
|
|
254
124
|
|
|
255
125
|
<div align="center">
|
|
256
126
|
<picture>
|
|
257
|
-
<img alt="
|
|
127
|
+
<img alt="SpecMem Features" src="./svg-sections/readme-features.svg" width="800">
|
|
258
128
|
</picture>
|
|
259
129
|
</div>
|
|
260
130
|
|
|
261
|
-
<br/>
|
|
262
|
-
|
|
263
|
-
| Feature | SpecMem | Cursor | Continue | Cody | mem0 |
|
|
264
|
-
|---------|:-------:|:------:|:--------:|:----:|:----:|
|
|
265
|
-
| Semantic Search | pgvector | Limited | No | Limited | Yes |
|
|
266
|
-
| Per-Project Isolation | **Yes** | No | No | No | No |
|
|
267
|
-
| Local Embeddings | **Free** | Cloud | Cloud | Cloud | Cloud |
|
|
268
|
-
| Multi-Agent | **Yes** | No | No | No | No |
|
|
269
|
-
| Session Memory | **Auto** | Manual | No | No | Manual |
|
|
270
|
-
| Code Tracebacks | **Yes** | No | Limited | Yes | No |
|
|
271
|
-
| Self-Hosted | **Yes** | No | Partial | No | Yes |
|
|
272
|
-
| MCP Native | **Yes** | No | No | No | No |
|
|
273
|
-
|
|
274
|
-
---
|
|
275
|
-
|
|
276
|
-
## Architecture
|
|
277
|
-
|
|
278
|
-
```
|
|
279
|
-
+------------------------------------------------------------------+
|
|
280
|
-
| CLAUDE (MCP Client) |
|
|
281
|
-
+------------------------------------------------------------------+
|
|
282
|
-
|
|
|
283
|
-
MCP Protocol
|
|
284
|
-
|
|
|
285
|
-
+------------------------------------------------------------------+
|
|
286
|
-
| SPECMEM MCP SERVER |
|
|
287
|
-
| +--------------------+ +--------------------+ +---------------+ |
|
|
288
|
-
| | Memory Tools | | Code Tools | | Team Tools | |
|
|
289
|
-
| | save_memory | | find_code_pointers | | send_message | |
|
|
290
|
-
| | find_memory | | drill_down | | read_messages | |
|
|
291
|
-
| | get_memory | | check_sync | | claim_task | |
|
|
292
|
-
| | smush_memories | | force_resync | | get_status | |
|
|
293
|
-
| +--------------------+ +--------------------+ +---------------+ |
|
|
294
|
-
+------------------------------------------------------------------+
|
|
295
|
-
|
|
|
296
|
-
+--------------------+--------------------+
|
|
297
|
-
| | |
|
|
298
|
-
+----------------+ +-----------------+ +------------------+
|
|
299
|
-
| Embedding | | PostgreSQL | | Coordination |
|
|
300
|
-
| Service | | + pgvector | | Server |
|
|
301
|
-
| (Frankenstein) | | | | (Port 8596) |
|
|
302
|
-
+----------------+ +-----------------+ +------------------+
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
### Core Components
|
|
306
|
-
|
|
307
|
-
**PostgreSQL + pgvector** - Battle-tested storage for 100k+ memories with vector similarity search.
|
|
308
|
-
|
|
309
|
-
**Frankenstein Embedding Service** - Local embedding generation. Zero API costs. No rate limits. Works offline. Your data never leaves your machine.
|
|
310
|
-
|
|
311
|
-
**Memory Types** - Cognitive architecture with episodic, semantic, procedural, working, and consolidated memory types.
|
|
312
|
-
|
|
313
|
-
**File Watcher** - Automatic codebase indexing. Changes detected and re-indexed in real-time.
|
|
314
|
-
|
|
315
|
-
---
|
|
316
|
-
|
|
317
|
-
## MCP Tools
|
|
318
|
-
|
|
319
|
-
SpecMem provides **74 MCP tools** organized into categories:
|
|
320
|
-
|
|
321
|
-
### Memory Operations
|
|
322
|
-
- `find_memory` - Semantic search by meaning
|
|
323
|
-
- `save_memory` - Store with tags and importance
|
|
324
|
-
- `get_memory` - Retrieve by ID
|
|
325
|
-
- `drill_down` - Full context exploration
|
|
326
|
-
- `smush_memories_together` - Consolidate similar memories
|
|
327
|
-
|
|
328
|
-
### Code Search
|
|
329
|
-
- `find_code_pointers` - Semantic code search with tracebacks
|
|
330
|
-
- `check_sync` - Verify codebase sync status
|
|
331
|
-
- `start_watching` / `stop_watching` - File watcher control
|
|
332
|
-
- `force_resync` - Full codebase rescan
|
|
333
|
-
|
|
334
|
-
### Team Coordination
|
|
335
|
-
- `send_team_message` - Message other agents
|
|
336
|
-
- `read_team_messages` - Check for updates
|
|
337
|
-
- `claim_task` / `release_task` - Coordinate work
|
|
338
|
-
- `request_help` / `respond_to_help` - Collaboration
|
|
339
|
-
|
|
340
|
-
### Session Management
|
|
341
|
-
- `extract-claude-sessions` - Pull session history
|
|
342
|
-
- `get-session-watcher-status` - Check extraction status
|
|
343
|
-
|
|
344
|
-
---
|
|
345
|
-
|
|
346
|
-
## Platform Requirements
|
|
347
|
-
|
|
348
|
-
| Requirement | Version |
|
|
349
|
-
|-------------|---------|
|
|
350
|
-
| Node.js | 18+ |
|
|
351
|
-
| PostgreSQL | 14+ with pgvector |
|
|
352
|
-
| Docker | 20+ (for embedding service) |
|
|
353
|
-
| Linux | Required (see below) |
|
|
354
|
-
|
|
355
|
-
### Linux Requirement
|
|
356
|
-
|
|
357
|
-
SpecMem is licensed for **Linux Operating Systems only**.
|
|
358
|
-
|
|
359
|
-
Windows users: The Windows Tax provision in the license requires commercial licensing. WSL/WSL2 counts as Windows for licensing purposes.
|
|
360
|
-
|
|
361
|
-
See [LICENSE.md](./LICENSE.md) Section 4 for Windows platform terms.
|
|
362
|
-
|
|
363
131
|
---
|
|
364
132
|
|
|
365
|
-
##
|
|
366
|
-
|
|
367
|
-
| Variable | Default | Description |
|
|
368
|
-
|----------|---------|-------------|
|
|
369
|
-
| `SPECMEM_DB_HOST` | localhost | PostgreSQL host |
|
|
370
|
-
| `SPECMEM_DB_PORT` | 5432 | PostgreSQL port |
|
|
371
|
-
| `SPECMEM_COORDINATION_PORT` | 8596 | Team server port |
|
|
372
|
-
| `SPECMEM_DASHBOARD_PORT` | 8585 | Web UI port |
|
|
373
|
-
| `SPECMEM_MEMORY_LIMIT` | 250 | Max heap MB |
|
|
374
|
-
|
|
375
|
-
---
|
|
376
|
-
|
|
377
|
-
## Troubleshooting
|
|
378
|
-
|
|
379
|
-
### Claude doesn't see memories
|
|
380
|
-
|
|
381
|
-
```bash
|
|
382
|
-
specmem health
|
|
383
|
-
cat specmem/run/mcp-startup.log
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
### Embedding server issues
|
|
387
|
-
|
|
388
|
-
```bash
|
|
389
|
-
docker ps | grep specmem
|
|
390
|
-
ls -la specmem/sockets/embeddings.sock
|
|
391
|
-
```
|
|
392
|
-
|
|
393
|
-
### Database errors
|
|
394
|
-
|
|
395
|
-
```bash
|
|
396
|
-
pg_isready
|
|
397
|
-
psql -U specmem -d specmem -c "SELECT 1"
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
| Error | Cause | Fix |
|
|
401
|
-
|-------|-------|-----|
|
|
402
|
-
| `ECONNREFUSED` | PostgreSQL down | `systemctl start postgresql` |
|
|
403
|
-
| `relation does not exist` | Schema missing | `specmem init` |
|
|
404
|
-
| `embedding socket not found` | Server crashed | Check logs, restart |
|
|
405
|
-
|
|
406
|
-
---
|
|
133
|
+
## What SpecMem Actually Does
|
|
407
134
|
|
|
408
|
-
|
|
135
|
+
> Most people look at SpecMem and think it's just a memory plugin. It's not. It's a full persistent intelligence layer for your Claude Code sessions, and honestly there's nothing else like it on npm right now.
|
|
409
136
|
|
|
410
|
-
|
|
137
|
+
### Semantic Code Memory
|
|
411
138
|
|
|
412
|
-
|
|
139
|
+
Every time you run `specmem init` on a project, it doesn't just save your conversations. It crawls your entire codebase and builds a real semantic graph of everything in it. We're talking functions, classes, methods, fields, constants, variables, enums, structs, interfaces, traits, macros, type aliases, constructors, destructors, operator overloads -the works. And it doesn't stop at definitions. It maps out every import, every dependency, every `#include`, every `use` statement, every `<script src>`. The whole dependency graph gets stored in PostgreSQL with pgvector embeddings so you can search it by meaning, not just by name.
|
|
413
140
|
|
|
414
|
-
|
|
141
|
+
When you ask Claude "where's that function that handles rate limiting?" -SpecMem doesn't do a dumb string match. It runs a semantic search across your entire codebase graph and finds `rateLimiter()`, `handleThrottle()`, `apiQuotaManager()`, plus all the conversations you've had about rate limiting. That's why it works.
|
|
415
142
|
|
|
416
|
-
|
|
143
|
+
<details>
|
|
144
|
+
<summary><strong>Language Support</strong> - TypeScript, JavaScript, Python, Java, Kotlin, Scala, Go, Rust, C, C++, HTML, Ruby, PHP, Swift</summary>
|
|
417
145
|
|
|
418
|
-
|
|
146
|
+
<br/>
|
|
419
147
|
|
|
420
|
-
|
|
148
|
+
Every language gets full dedicated analysis with proper extraction of all definitions and dependencies:
|
|
421
149
|
|
|
422
150
|
| Language | What Gets Indexed |
|
|
423
151
|
|----------|------------------|
|
|
@@ -425,82 +153,111 @@ Here's every language that gets full dedicated analysis with proper extraction o
|
|
|
425
153
|
| **Python** | Functions, async functions, classes, methods (with `self`/`cls` detection), module-level constants. `import` and `from...import` statements. Indentation-based scope tracking. |
|
|
426
154
|
| **Java** | Classes, abstract classes, interfaces, enums, records (Java 14+), annotations (@interface), constructors, methods, fields (private/protected/public/static/final), static initializer blocks. Package declarations, imports, static imports, wildcard imports. |
|
|
427
155
|
| **Kotlin** | Everything Java gets plus `fun`, `val`/`var`, `data class`, `object`/`companion object`, `suspend` functions, `internal` visibility. Same import handling. |
|
|
428
|
-
| **Scala** | Shares the Java/Kotlin extractor
|
|
156
|
+
| **Scala** | Shares the Java/Kotlin extractor -picks up classes, traits, objects, methods, vals. |
|
|
429
157
|
| **Go** | Functions, methods (with receivers), structs, interfaces, types, constants, variables. Single and block imports. Exported detection via capitalization. |
|
|
430
158
|
| **Rust** | Functions, async functions, structs, enums, traits, impl blocks, constants, statics. `use` statements with nested paths, `extern crate`. Pub detection. |
|
|
431
159
|
| **C / C++** | Functions, methods, classes, structs, unions, enums (including `enum class`), namespaces, typedefs, `using` aliases, constructors, destructors, operator overloads, macros (#define with and without params), global/static/extern/constexpr/thread_local variables. `#include` (angle vs quote, STL builtin detection), `using namespace`, `using` declarations. Template support. Virtual/inline/const method detection. |
|
|
432
160
|
| **HTML** | Elements with IDs, CSS classes, `<script>` and `<style>` blocks, forms, templates, web components (`<slot>`, `<component>`), `data-*` attributes, semantic sections. Script src, stylesheet links, image/iframe/source assets, inline ES module imports. Structural chunking by HTML blocks. |
|
|
433
161
|
| **Ruby, PHP, Swift** | Analyzable with generic extraction (function/class detection). Dedicated extractors coming. |
|
|
434
162
|
|
|
435
|
-
That's not a marketing list
|
|
163
|
+
That's not a marketing list -every one of those has real regex-based extraction that's been tested against actual codebases. The Java extractor alone handles annotations, records, static initializers, field visibility, and constructor detection. The C++ extractor picks up operator overloads and destructor naming. We didn't cut corners on this.
|
|
164
|
+
|
|
165
|
+
</details>
|
|
436
166
|
|
|
437
|
-
### Chat Session Memory
|
|
167
|
+
### Chat Session Memory
|
|
438
168
|
|
|
439
169
|
Every conversation you have with Claude gets stored as a memory with full semantic embeddings. Next session, Claude can search through your past discussions by meaning. You talked about a JWT refresh token edge case three weeks ago? SpecMem finds it. You discussed why you chose PostgreSQL over MongoDB for the user service? It's there. Your conversations don't vanish when you close the terminal anymore.
|
|
440
170
|
|
|
441
171
|
Memories get tagged by type (conversation, decision, architecture, bug, etc.), importance level, and project. They're searchable with `find_memory`, drillable with `drill_down`, and you can link related ones together with `link_the_vibes`. It's your project's institutional knowledge, but it actually works.
|
|
442
172
|
|
|
443
|
-
### Token Compression — 60% Smaller Context
|
|
444
|
-
|
|
445
|
-
SpecMem uses Traditional Chinese-based compression that squeezes your context down by about 60%. That's not a typo. The same information that would eat 1000 tokens takes about 400 tokens in compressed form. Claude reads it with 99%+ accuracy. This means your context window goes further, you hit fewer limits, and long sessions don't fall apart as fast.
|
|
446
|
-
|
|
447
173
|
### Multi-Agent Team Coordination
|
|
448
174
|
|
|
449
|
-
|
|
175
|
+
**Compatible with Claude Code Agent Teams** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). SpecMem acts as the persistent coordination layer - unlimited dynamic swarm channels, semantic memory search across all agents, and team comms that survive session restarts. Native Claude teammates get SpecMem MCP tools auto-injected. Swarm leaders can deploy sub-agents with custom prompts through the agent-loading-hook system.
|
|
176
|
+
|
|
177
|
+
<div align="center">
|
|
178
|
+
<picture>
|
|
179
|
+
<img alt="Multi-Agent Coordination" src="./svg-sections/readme-multi-agent.svg" width="800">
|
|
180
|
+
</picture>
|
|
181
|
+
</div>
|
|
450
182
|
|
|
451
|
-
|
|
183
|
+
<details>
|
|
184
|
+
<summary><strong>74+ MCP Tools</strong> - Memory search, code pointers, team comms, file watching, stats, drilldown, sync checking, and more</summary>
|
|
452
185
|
|
|
453
|
-
|
|
186
|
+
<br/>
|
|
454
187
|
|
|
455
|
-
|
|
188
|
+
SpecMem ships with over 74 MCP tools out of the box. Every tool is available as a slash command too. `/specmem-find`, `/specmem-code`, `/specmem-pointers`, `/specmem-stats`, `/specmem-remember` -whatever you need.
|
|
456
189
|
|
|
457
|
-
|
|
190
|
+
| Category | Tools |
|
|
191
|
+
|----------|-------|
|
|
192
|
+
| **Memory** | `find_memory`, `save_memory`, `get_memory`, `drill_down`, `smush_memories_together`, `link_the_vibes` |
|
|
193
|
+
| **Code Search** | `find_code_pointers`, `check_sync`, `start_watching`, `stop_watching`, `force_resync`, `spatial_search` |
|
|
194
|
+
| **Team** | `send_team_message`, `read_team_messages`, `claim_task`, `release_task`, `request_help`, `broadcast_to_team` |
|
|
195
|
+
| **Session** | `extract_claude_sessions`, `get_session_watcher_status`, `smart_recall`, `smart_search` |
|
|
196
|
+
| **System** | `show_me_the_stats`, `memory_health_check`, `export_project_memories`, `import_project_memories` |
|
|
458
197
|
|
|
459
|
-
|
|
198
|
+
</details>
|
|
460
199
|
|
|
461
|
-
|
|
200
|
+
<details>
|
|
201
|
+
<summary><strong>The Embedding Server</strong> - Your code, your machine, not OpenAI's training data</summary>
|
|
462
202
|
|
|
463
|
-
|
|
203
|
+
<br/>
|
|
464
204
|
|
|
465
|
-
We
|
|
205
|
+
We run our own embedding server locally in Docker. Your code never leaves your machine. No API calls to OpenAI or anyone else. The embeddings get stored in PostgreSQL with pgvector and they're used for all semantic search operations. It's fast, it's private, and it doesn't cost you anything per query.
|
|
466
206
|
|
|
467
|
-
|
|
207
|
+
</details>
|
|
468
208
|
|
|
469
|
-
|
|
209
|
+
---
|
|
470
210
|
|
|
471
|
-
|
|
211
|
+
## 📊 Real-World Performance
|
|
472
212
|
|
|
473
|
-
|
|
213
|
+
<div align="center">
|
|
214
|
+
<picture>
|
|
215
|
+
<img alt="Real-World Performance" src="./svg-sections/readme-performance.svg" width="800">
|
|
216
|
+
</picture>
|
|
217
|
+
</div>
|
|
474
218
|
|
|
475
|
-
|
|
219
|
+
---
|
|
476
220
|
|
|
477
|
-
|
|
221
|
+
## 🆕 What's New in v3.7
|
|
478
222
|
|
|
479
|
-
|
|
223
|
+
<div align="center">
|
|
224
|
+
<picture>
|
|
225
|
+
<img alt="What's New in v3.7" src="./svg-sections/readme-whats-new.svg" width="800">
|
|
226
|
+
</picture>
|
|
227
|
+
</div>
|
|
480
228
|
|
|
481
229
|
---
|
|
482
230
|
|
|
483
|
-
##
|
|
231
|
+
## 🏗 Architecture
|
|
484
232
|
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
233
|
+
<div align="center">
|
|
234
|
+
<picture>
|
|
235
|
+
<img alt="Architecture" src="./svg-sections/readme-architecture.svg" width="800">
|
|
236
|
+
</picture>
|
|
237
|
+
</div>
|
|
488
238
|
|
|
489
239
|
---
|
|
490
240
|
|
|
491
|
-
##
|
|
241
|
+
## 💻 Platform Requirements
|
|
492
242
|
|
|
493
|
-
|
|
243
|
+
<div align="center">
|
|
244
|
+
<picture>
|
|
245
|
+
<img alt="Platform Requirements" src="./svg-sections/readme-platform.svg" width="800">
|
|
246
|
+
</picture>
|
|
247
|
+
</div>
|
|
494
248
|
|
|
495
|
-
|
|
249
|
+
> [!IMPORTANT]
|
|
250
|
+
> SpecMem is licensed for **Linux Operating Systems only**. Windows users need commercial licensing (WSL/WSL2 counts as Windows). See [LICENSE.md](./LICENSE.md) Section 4.
|
|
496
251
|
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
- **Training Prohibited** - $1M+ statutory damages per model trained
|
|
501
|
-
- **Revenue Tiers** - Commercial licensing based on organization revenue
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## 🛠 MCP Tools
|
|
502
255
|
|
|
503
|
-
|
|
256
|
+
<div align="center">
|
|
257
|
+
<picture>
|
|
258
|
+
<img alt="MCP Tools" src="./svg-sections/readme-mcp-tools.svg" width="800">
|
|
259
|
+
</picture>
|
|
260
|
+
</div>
|
|
504
261
|
|
|
505
262
|
---
|
|
506
263
|
|
|
@@ -512,7 +269,8 @@ cd specmem
|
|
|
512
269
|
npm install && npm run build && npm test
|
|
513
270
|
```
|
|
514
271
|
|
|
515
|
-
|
|
272
|
+
<details>
|
|
273
|
+
<summary><strong>Project Structure</strong></summary>
|
|
516
274
|
|
|
517
275
|
```
|
|
518
276
|
src/mcp/ # MCP server
|
|
@@ -522,20 +280,43 @@ claude-hooks/ # Hooks for ~/.claude
|
|
|
522
280
|
embedding-sandbox/ # Embedding server
|
|
523
281
|
```
|
|
524
282
|
|
|
525
|
-
|
|
283
|
+
</details>
|
|
526
284
|
|
|
527
|
-
|
|
285
|
+
---
|
|
528
286
|
|
|
529
287
|
<details>
|
|
530
|
-
<summary><strong>
|
|
288
|
+
<summary><strong>Read if you work for Anthropic or develop code</strong></summary>
|
|
289
|
+
|
|
290
|
+
<br/>
|
|
291
|
+
|
|
292
|
+
<div align="center">
|
|
293
|
+
|
|
294
|
+
<!-- Training Prohibited Notice -->
|
|
295
|
+
<picture>
|
|
296
|
+
<source media="(prefers-color-scheme: dark)" srcset="./svg-sections/notice-training-prohibited.svg">
|
|
297
|
+
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-training-prohibited.svg">
|
|
298
|
+
<img alt="TRAINING PROHIBITED" src="./svg-sections/notice-training-prohibited.svg" width="800">
|
|
299
|
+
</picture>
|
|
531
300
|
|
|
532
301
|
<br/>
|
|
533
302
|
|
|
534
|
-
|
|
303
|
+
<!-- IP Protection Notice -->
|
|
304
|
+
<picture>
|
|
305
|
+
<source media="(prefers-color-scheme: dark)" srcset="./svg-sections/notice-ip-protected.svg">
|
|
306
|
+
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-ip-protected.svg">
|
|
307
|
+
<img alt="Intellectual Property Protected" src="./svg-sections/notice-ip-protected.svg" width="700">
|
|
308
|
+
</picture>
|
|
309
|
+
|
|
310
|
+
</div>
|
|
311
|
+
|
|
312
|
+
</details>
|
|
313
|
+
|
|
314
|
+
---
|
|
535
315
|
|
|
536
|
-
|
|
316
|
+
<details>
|
|
317
|
+
<summary><strong>License Summary</strong></summary>
|
|
537
318
|
|
|
538
|
-
|
|
319
|
+
<br/>
|
|
539
320
|
|
|
540
321
|
- **PRE-RELEASE:** No license granted until official announcement at https://justcalljon.pro/specmem
|
|
541
322
|
- **AI/ML TRAINING PROHIBITED:** Section 9 explicitly prohibits use for model training ($1M+ damages)
|
|
@@ -561,6 +342,19 @@ Copyright (c) 2024-2026 Hardwick Software Services / Jon Hardwick. All Rights Re
|
|
|
561
342
|
|
|
562
343
|
<div align="center">
|
|
563
344
|
|
|
345
|
+
<!-- License Pre-Release Notice -->
|
|
346
|
+
<picture>
|
|
347
|
+
<source media="(prefers-color-scheme: dark)" srcset="./svg-sections/notice-license-prerelease.svg">
|
|
348
|
+
<source media="(prefers-color-scheme: light)" srcset="./svg-sections/notice-license-prerelease.svg">
|
|
349
|
+
<img alt="LICENSE NOT GRANT - Pre-Release" src="./svg-sections/notice-license-prerelease.svg" width="800">
|
|
350
|
+
</picture>
|
|
351
|
+
|
|
352
|
+
</div>
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
<div align="center">
|
|
357
|
+
|
|
564
358
|
<br/>
|
|
565
359
|
|
|
566
360
|
<picture>
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"sessionId":"unknown","timestamp":1768086339845}
|
|
File without changes
|
package/commands/specmem-code.md
CHANGED
|
File without changes
|
|
File without changes
|
package/commands/specmem-find.md
CHANGED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
package/commands/specmem.md
CHANGED
|
File without changes
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"lastInput":" NO AI ATTRIBUTION PERMITTED! Bet that shit up lil nig, deploy.sh patch -> Wipe github commit history, update all github SOURCE files to curent -- do not replace license changelog svgs or pages, your goal is to make the girhub have updated files but appear as if first commit, ensure no ai attribution, wipe commit and push history, wipe release history and make the 3.5.3 the new release","lastInputTime":1769974346692,"buffer":"NO AI ATTRIBUTION PERMITTED! Bet that shit up lil nig, deploy.sh patch -> Wipe github commit history, update all github SOURCE files to curent -- do not replace license changelog svgs or pages, your goal is to make the girhub have updated files but appear as if first commit, ensure no ai attribution, wipe commit and push history, wipe release history and make the 3.5.3 the new release"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specmem-hardwicksoftware",
|
|
3
|
-
"version": "3.7.
|
|
3
|
+
"version": "3.7.22",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Your Claude Code sessions don't have to start from scratch anymore — SpecMem gives your AI real memory. It won't forget your conversations, your code, or your architecture decisions between sessions. That's the whole point. Semantic code indexing that actually works: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C, C++, HTML and more. It doesn't just track functions — it gets classes, methods, fields, constants, enums, macros, imports, structs, the whole codebase graph. There's chat memory too, powered by pgvector embeddings. You've also got token compression, team coordination, multi-agent comms, and file watching built in. 74+ MCP tools. Runs on PostgreSQL + Docker. It's kind of a big deal. justcalljon.pro",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -35,7 +35,9 @@
|
|
|
35
35
|
},
|
|
36
36
|
"keywords": [
|
|
37
37
|
"mcp",
|
|
38
|
+
"mcp-server",
|
|
38
39
|
"memory",
|
|
40
|
+
"persistent-memory",
|
|
39
41
|
"semantic-search",
|
|
40
42
|
"pgvector",
|
|
41
43
|
"ai",
|
|
@@ -43,19 +45,33 @@
|
|
|
43
45
|
"claude-code",
|
|
44
46
|
"anthropic",
|
|
45
47
|
"embeddings",
|
|
48
|
+
"local-embeddings",
|
|
46
49
|
"context",
|
|
47
50
|
"hooks",
|
|
48
51
|
"code-indexing",
|
|
52
|
+
"codebase-analysis",
|
|
53
|
+
"multi-agent",
|
|
54
|
+
"swarm",
|
|
55
|
+
"agent-teams",
|
|
56
|
+
"team-coordination",
|
|
57
|
+
"self-hosted",
|
|
58
|
+
"developer-tools",
|
|
49
59
|
"typescript",
|
|
50
60
|
"javascript",
|
|
51
61
|
"python",
|
|
52
62
|
"java",
|
|
63
|
+
"kotlin",
|
|
53
64
|
"cpp",
|
|
54
65
|
"rust",
|
|
66
|
+
"golang",
|
|
55
67
|
"html",
|
|
56
|
-
"codebase-analysis",
|
|
57
68
|
"multi-language",
|
|
58
|
-
"
|
|
69
|
+
"linux",
|
|
70
|
+
"nodejs",
|
|
71
|
+
"postgres",
|
|
72
|
+
"session-memory",
|
|
73
|
+
"code-search",
|
|
74
|
+
"cli"
|
|
59
75
|
],
|
|
60
76
|
"author": {
|
|
61
77
|
"name": "Jonathan Hardwick",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"sessionId":"22e2b1f0-de28-42cd-88cc-9a2dbe70f74f","timestamp":1769059773073}
|
package/specmem.env
CHANGED
|
File without changes
|