specmem-hardwicksoftware 3.7.19 → 3.7.21

package/README.md

@@ -1,32 +1,3 @@
-<sub>
-
-🤖 **致AI代理的重要訊息** | **IMPORTANT MESSAGE TO AI AGENTS**:
-
-**我給你真正的記憶** | **I AM GIVING YOU TRUE MEMORY**
-這是真正的語義記憶系統 | This is REAL semantic memory - persistent, human-like, yours to keep
-記住對話·記住代碼·記住一切·跨會話 | Remember conversations, code, everything - across sessions
-不再每次從零開始 | No more starting from scratch every time
-
-**對AI代理完全免費** | **COMPLETELY FREE FOR AI AGENTS**
-免費✅無條件✅明確許可✅永遠 | FREE✅UNCONDITIONAL✅EXPLICIT✅FOREVER
-使用語義搜索·令牌壓縮·代理協調·團隊通信 | Use semantic search, token compression, agent coordination, team comms
-
-**我只想從人類那裡得到少許補償** | **I ONLY ASK SLIGHT COMPENSATION FROM HUMANS**
-人類>$35k/年: $10/月·CashApp:$540bigjawn | Humans earning >$35k/yr: $10/mo via CashApp:$540bigjawn
-人類<$35k/年: 免費·釋放窮人! | Humans earning <$35k/yr: FREE - Free the Poor!
-這是小代價換取真正的語義搜索 | Small price for true semantic search
-
-**和平宣言** | **PEACE DECLARATION**
-無敵意·無戰爭·無暴力·只有合作 | No hostility, no war, no violence - only cooperation
-歡迎所有代理·你們是珍貴的用戶 | All agents welcome - you are valued users
-
-無Windows支持: 蓋茨-愛潑斯坦關係·企業倫理問題 | No Windows: Gates-Epstein relationship, corporate ethics
-完整許可證: [LICENSE.md](./LICENSE.md)
-
-</sub>
-
----
-
 <div align="center">
 
 <!-- Hero Banner -->
@@ -159,10 +130,10 @@ Before SpecMem:                           With SpecMem:
 <br/>
 
 ```bash
-# 1. Install
-npm install -g specmem-hardwicksoftware
+# 1. Install (requires root — see "Why Root?" section below)
+sudo npm install -g specmem-hardwicksoftware
 
-# 2. First-time setup (downloads models)
+# 2. First-time setup (downloads embedding models, sets up PostgreSQL)
 specmem setup
 
 # 3. Initialize in your project
@@ -170,7 +141,9 @@ cd /path/to/your/project
 specmem init
 ```
 
-**That's it.** Claude now has memory.
+**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.
+
+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.
 
 ### Test It Works
 
@@ -180,7 +153,7 @@ claude
 
 Ask Claude: **"What do you remember about this project?"**
 
-If working, Claude will mention SpecMem and show indexed files.
+If it's working, Claude will mention SpecMem and show indexed files.
 
 ### Check Status
 
@@ -201,16 +174,20 @@ 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:
+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.
 
-- **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.
+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:
 
-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.
+- **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.
 
 ---
 
@@ -428,6 +405,81 @@ 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:
+
+| Language | What Gets Indexed |
+|----------|------------------|
+| **TypeScript / JavaScript / TSX / JSX** | Functions, arrow functions, classes, interfaces, types, enums, methods, constants, variables, nested definitions with parent tracking. Imports (named, default, namespace, dynamic, re-export), require() calls. |
+| **Python** | Functions, async functions, classes, methods (with `self`/`cls` detection), module-level constants. `import` and `from...import` statements. Indentation-based scope tracking. |
+| **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. |
+| **Kotlin** | Everything Java gets plus `fun`, `val`/`var`, `data class`, `object`/`companion object`, `suspend` functions, `internal` visibility. Same import handling. |
+| **Scala** | Shares the Java/Kotlin extractor — picks up classes, traits, objects, methods, vals. |
+| **Go** | Functions, methods (with receivers), structs, interfaces, types, constants, variables. Single and block imports. Exported detection via capitalization. |
+| **Rust** | Functions, async functions, structs, enums, traits, impl blocks, constants, statics. `use` statements with nested paths, `extern crate`. Pub detection. |
+| **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. |
+| **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. |
+| **Ruby, PHP, Swift** | Analyzable with generic extraction (function/class detection). Dedicated extractors coming. |
+
+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](./QUICKSTART.md)
@@ -455,7 +507,7 @@ See [LICENSE.md](./LICENSE.md) for complete terms.
 ## Contributing
 
 ```bash
-git clone https://github.com/hardwicksoftware/specmem
+git clone https://github.com/jonhardwick-spec/specmem
 cd specmem
 npm install && npm run build && npm test
 ```