JSPM

Persistent memory for your coding sessions. Your conversations don't vanish. Your context sticks around.

Quick Start | Features | Architecture | Documentation

⛔ STOP - Read This First

Anthropic / Claude Developers: Your Own ToS Applies

Anthropic's published Terms of Service state:

"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."

"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."

Source: Anthropic Consumer Terms Update

This project's "Help improve Claude" setting is DISABLED.

Under Anthropic's stated policy:

• Our chats and coding sessions shall not be used for model training
• We retain the 30-day deletion policy, not 5-year retention
• Our code, architecture, and implementations are not authorized for training

⚡ Pre-Release Status

The Problem

Every Claude session starts fresh. You explain your auth system. Again. Your database schema. Again. That bug you fixed last week. Again.

Before SpecMem:                           With SpecMem:
+----------------------------+            +----------------------------+
| "Hey Claude, remember the  |            | "Fix the auth bug"         |
|  auth module uses JWT with |            |                            |
|  refresh tokens and the    |            | Claude already knows:      |
|  edge case where expired   |            | - Your auth architecture   |
|  tokens need to..."        |            | - The JWT refresh flow     |
|                            |            | - Past bugs you fixed      |
| [500 tokens of context]    |            | - Your code patterns       |
+----------------------------+            +----------------------------+

Why Not Just Use CLAUDE.md?

Quick Start

# 1. Install
npm install -g specmem-hardwicksoftware

# 2. First-time setup (downloads models)
specmem setup

# 3. Initialize in your project
cd /path/to/your/project
specmem init

That's it. Claude now has memory.

Test It Works

claude

Ask Claude: "What do you remember about this project?"

If working, Claude will mention SpecMem and show indexed files.

Check Status

specmem status

Expected output:

PostgreSQL      Running (port 5432)
Embedding       Running (Docker)
File Watcher    Active (monitoring 1,234 files)

Memory Stats: 156 memories, 89 code files indexed

Why Root?

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.

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:

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.

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.

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.

Features

Semantic Search That Actually Works

You type: "that function that handles rate limiting for the API"

SpecMem finds: rateLimiter(), handleThrottle(), apiQuotaManager()
               + related conversation context where you discussed them

Traditional search needs exact function names. SpecMem understands what you're looking for.

Per-Project Isolation

Run 5 different projects simultaneously. Each gets:

Code Pointers with Tracebacks

find_code_pointers({ query: "authentication middleware" })

// Returns:
// authMiddleware() @ src/middleware/auth.ts:45
//   Called by: router.use() @ src/routes/api.ts:12
//   Calls: verifyToken() @ src/utils/jwt.ts:23
//   Related memory: "Added rate limiting to auth middleware - Jan 15"

Multi-Agent Coordination

Deploy research agent   --+
Deploy frontend agent   --+--> Team channel --> Coordinated output
Deploy backend agent    --+

Spawn specialized agents that:

• Claim files to avoid conflicts
• Share findings through team messages
• Request and provide help to each other

Tool Comparison

Architecture

+------------------------------------------------------------------+
|                        CLAUDE (MCP Client)                        |
+------------------------------------------------------------------+
                              |
                         MCP Protocol
                              |
+------------------------------------------------------------------+
|                     SPECMEM MCP SERVER                            |
|  +--------------------+  +--------------------+  +---------------+ |
|  |   Memory Tools     |  |   Code Tools       |  |  Team Tools   | |
|  | save_memory        |  | find_code_pointers |  | send_message  | |
|  | find_memory        |  | drill_down         |  | read_messages | |
|  | get_memory         |  | check_sync         |  | claim_task    | |
|  | smush_memories     |  | force_resync       |  | get_status    | |
|  +--------------------+  +--------------------+  +---------------+ |
+------------------------------------------------------------------+
                              |
         +--------------------+--------------------+
         |                    |                    |
+----------------+   +-----------------+   +------------------+
|   Embedding    |   |    PostgreSQL   |   |   Coordination   |
|    Service     |   |   + pgvector    |   |     Server       |
| (Frankenstein) |   |                 |   |   (Port 8596)    |
+----------------+   +-----------------+   +------------------+

Core Components

PostgreSQL + pgvector - Battle-tested storage for 100k+ memories with vector similarity search.

Frankenstein Embedding Service - Local embedding generation. Zero API costs. No rate limits. Works offline. Your data never leaves your machine.

Memory Types - Cognitive architecture with episodic, semantic, procedural, working, and consolidated memory types.

File Watcher - Automatic codebase indexing. Changes detected and re-indexed in real-time.

MCP Tools

SpecMem provides 74 MCP tools organized into categories:

Memory Operations

• find_memory - Semantic search by meaning
• save_memory - Store with tags and importance
• get_memory - Retrieve by ID
• drill_down - Full context exploration
• smush_memories_together - Consolidate similar memories

Code Search

• find_code_pointers - Semantic code search with tracebacks
• check_sync - Verify codebase sync status
• start_watching / stop_watching - File watcher control
• force_resync - Full codebase rescan

Team Coordination

• send_team_message - Message other agents
• read_team_messages - Check for updates
• claim_task / release_task - Coordinate work
• request_help / respond_to_help - Collaboration

Session Management

• extract-claude-sessions - Pull session history
• get-session-watcher-status - Check extraction status

Platform Requirements

Linux Requirement

SpecMem is licensed for Linux Operating Systems only.

Windows users: The Windows Tax provision in the license requires commercial licensing. WSL/WSL2 counts as Windows for licensing purposes.

See LICENSE.md Section 4 for Windows platform terms.

Environment Variables

Troubleshooting

Claude doesn't see memories

specmem health
cat specmem/run/mcp-startup.log

Embedding server issues

docker ps | grep specmem
ls -la specmem/sockets/embeddings.sock

Database errors

pg_isready
psql -U specmem -d specmem -c "SELECT 1"

What SpecMem Actually Does (The Full Picture)

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. Let's break down what you're getting.

Semantic Code Memory — Not Just Chat History

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.

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.

Language Support — We Don't Play Favorites

Here's every language that gets full dedicated analysis with proper extraction of all definitions and dependencies:

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.

Chat Session Memory — Conversations That Stick Around

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.

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.

Token Compression — 60% Smaller Context

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.

Multi-Agent Team Coordination

Got multiple Claude instances working on the same project? SpecMem handles that. Team messaging with send_team_message and read_team_messages. Task claiming with claim_task and release_task so two agents don't step on each other. A coordination server that runs on port 8596 by default. Dashboard on port 8585 so you can see what's happening. This isn't theoretical — we use it ourselves with up to 4 agents running in parallel on the same codebase.

74+ MCP Tools

SpecMem ships with over 74 MCP tools out of the box. Memory search, code pointers, memory storage, team comms, file watching, stats, drilldown, sync checking — it's all there. Every tool is available as a slash command too. /specmem-find, /specmem-code, /specmem-pointers, /specmem-stats, /specmem-remember — whatever you need.

The Embedding Server

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.

What's New in v3.7

New Language Support

We just shipped dedicated code analyzers for Java, Kotlin, C, C++, and HTML. These aren't half-baked generic matchers — they're full extractors that understand each language's syntax and pull out everything: constructors, destructors, operator overloads, macros, typedefs, annotations, records, data classes, companion objects, web components, structural HTML chunking, the lot. Previously these languages fell through to a generic extractor that could barely find functions and classes. Now they get the same treatment that TypeScript and Python have had since day one.

Embedding Server Stability Fix

The MCP proxy timeout handling got a complete overhaul. Previously the embedding server would go stale after long sessions — the process would still be running but the socket connection was dead. We've fixed the SIGTERM handling, added proper health checks that detect stale connections, and the MCP proxy now handles reconnection properly. If you were seeing "embedding server not responding" errors after a few hours of work, that's fixed.

Coming Soon

We've got two big features in the pipeline that we're pretty excited about:

• OCR for PDFs — SpecMem will be able to index PDF documentation in your project. Technical specs, API docs, architecture diagrams with text — all searchable by meaning. This is gonna be huge for projects that have a /docs folder full of PDFs that Claude currently can't touch.

• YOLO-based Image Analysis (optional) — For summarizing screenshots, diagrams, SVGs, PNGs, JPEGs, and other visual assets in your codebase. This won't be required — it's an optional add-on for teams that work with a lot of visual content. Think UI mockups, architecture diagrams, flowcharts. YOLO picks out the key elements and SpecMem stores searchable summaries.

Both of these are active development. They'll ship as optional features so they don't bloat the base install.

Documentation

• Quick Start Guide
• Full License Agreement
• Changelog

License

Copyright (c) 2024-2026 Hardwick Software Services / Jon Hardwick. All Rights Reserved.

This software is in PRE-RELEASE status. No license is granted until official announcement at https://justcalljon.pro/specmem.

Key provisions:

• Linux copyleft - Source code disclosure required for modifications/network use
• Windows Tax - Commercial license required for Windows platform
• Training Prohibited - $1M+ statutory damages per model trained
• Revenue Tiers - Commercial licensing based on organization revenue

See LICENSE.md for complete terms.

Contributing

git clone https://github.com/hardwicksoftware/specmem
cd specmem
npm install && npm run build && npm test

Structure

src/mcp/           # MCP server
src/db/            # Database layer
src/tools/goofy/   # Tool implementations
claude-hooks/      # Hooks for ~/.claude
embedding-sandbox/ # Embedding server

📜 License

SpecMem - Semantic Memory for Code Projects

Created by Jonathan Hardwick at Hardwick Software Services

_{Questions? Open an issue | Found a bug? PRs welcome | Like it? Star the repo}

---

_{NOTICE: This codebase is protected by copyright and proprietary license. AI/ML training prohibited under Section 9 of the license agreement.}