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?

SpecMem isn't a simple npm package you drop into a project folder - it's a system-level tool that touches a lot of stuff your regular user account can't reach. Here's what it actually does and why it can't work without root:

• System-wide hooks get installed to ~/.claude/hooks/ - these intercept and augment tool calls in real-time. They aren't project-scoped, they're user-scoped, and writing to those directories from a global install needs elevated permissions.
• Docker container management - SpecMem spins up PostgreSQL with the pgvector extension in Docker. It creates containers, manages volumes, and handles networking. Docker's socket (/var/run/docker.sock) typically requires root or docker group membership.
• 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.
• Screen sessions for background services - the embedding server, file watcher, and MCP server all run in detached screen sessions. Managing those system-wide requires the right permissions.
• PostgreSQL database setup - first-run creates the database, enables pgvector, runs migrations, and sets up per-project schemas. It's touching system-level database configs.
• File watching across your entire codebase - chokidar watches thousands of files and needs access to whatever directories you're working in.

Bottom line: 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 needs to run as system services, and system services need root. There's no way to fake it with a local install.

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"

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