sessionmem 1.3.0 → 1.5.0

package/docs/troubleshooting.md

@@ -0,0 +1,126 @@
+# Troubleshooting
+
+This guide covers install failures, adapter (MCP host) issues, and `better-sqlite3` native-build failures. Configuration lives in `~/.sessionmem/config.json`.
+
+## Run offline diagnostics
+
+```bash
+sessionmem doctor
+sessionmem doctor --adapter claude-code  # select one host explicitly
+```
+
+Doctor prints PASS or FAIL and a fix hint for each problem. Any failed check
+returns a nonzero exit status. It checks:
+
+- **Memory store:** the selected database exists, opens, and passes SQLite's quick integrity check. It does not create a missing database.
+- **Schema:** all bundled migrations have been applied. It reports pending or unrecognized migrations without changing the schema.
+- **Hooks, per host:** Claude Code's SessionStart, SessionEnd, and PostToolUse commands, types, matchers, and enabled state match the current version's definitions. Other hosts report that lifecycle hooks are not required.
+- **Adapter wiring, per host:** the installed MCP entry matches the installer, its local command starts, the server version matches, and the expected tools and stats response work. This tests the configured server process without starting the coding agent itself.
+- **Recall:** the real memory service writes and retrieves a canary in a separate temporary project. The transaction is rolled back on success or failure, including index and access-count changes.
+
+For Codex, the wiring check supports the installer-generated TOML command and
+args. Custom Codex launch settings require manual verification.
+
+All checks work offline, including when cloud summarization is enabled. Doctor
+does not summarize sessions or sync shared memories. It honors `SESSIONMEM_DB_PATH`
+and the same host overrides as install. Keep those environment settings when
+running a suggested repair.
+
+Safe repair commands printed by doctor include:
+
+```bash
+sessionmem ping                         # initialize a missing store / apply pending migrations
+sessionmem install --adapter claude-code # repair MCP registration and hook definitions
+```
+
+Re-run doctor after repair. A corrupt store, a database from a newer version,
+globally disabled hooks, or missing filesystem permissions needs the indicated
+manual repair first; doctor does not delete data or downgrade a schema.
+
+## Install failures
+
+### `config.json` not written
+
+`sessionmem install` creates `~/.sessionmem/config.json` only if the file is missing. It leaves an existing config unchanged. To restore defaults, move or delete the old file and re-run `sessionmem install`. To change individual settings, use `sessionmem config set`.
+
+### Adapter not detected
+
+`install` discovers installed hosts from executables on the machine, including
+from a plain terminal. Automatic discovery currently supports Claude Code on
+`PATH`, `~/.local/bin/claude`, or `~/.claude/local/claude` (including Windows
+executable extensions). It does not rely on an active agent session or treat a
+leftover config directory as proof that the host is installed.
+
+If no supported host is found, install exits nonzero before creating files. Put
+Claude Code on `PATH` or select a host with `sessionmem install --adapter <name>`.
+Use the flag for other adapters, such as `--adapter cline` or `--adapter windsurf`,
+and for automation. Run `sessionmem doctor --adapter <name>` afterward. The
+`SESSIONMEM_ADAPTER` environment variable is also supported; the flag wins.
+
+### Command not found
+
+If `sessionmem` is not on your `PATH` after `npm install -g sessionmem`, your npm global bin directory is not on `PATH`. Add npm's global prefix `bin` to your shell `PATH`, or invoke via `npx sessionmem`.
+
+## Adapter issues
+
+Each MCP host uses its own adapter. If the server starts but memories are missing, check the host's configuration:
+
+- **Claude Code**: if memories are not injected at session start, run `sessionmem doctor --adapter claude-code`. Re-run `sessionmem install --adapter claude-code` to refresh the registration in `~/.claude.json` and all three hooks in `~/.claude/settings.json`, then restart the agent.
+- **Cursor**: run `sessionmem doctor --adapter cursor`, repair registration with `sessionmem install --adapter cursor`, and restart Cursor so it reloads MCP servers.
+- **Generic MCP host**: for any other MCP-compatible host, ensure the host is configured to launch `sessionmem run` as the MCP server command. If the host starts but no memory appears, check that the working directory matches the project whose memories you expect.
+
+If commands hang after the host loads, run `sessionmem doctor --adapter <name>`
+to check the configured MCP command as well as local database access. A missing
+`sessionmem` executable, stale server version, or failed MCP response fails the
+adapter wiring check. Fix `PATH` for the environment that starts your host too.
+
+## "0 sessions" / no session data recorded
+
+If `sessionmem savings` reports no session data or `sessionmem stats` shows `sessions: 0`, check the following.
+
+### The hooks are not installed
+
+Session events are captured by a `PostToolUse` hook that `sessionmem install` registers in `~/.claude/settings.json`. If you installed sessionmem before the auto-ingest hook existed, that hook is missing. Re-run `sessionmem install` (it is idempotent) and restart your editor, then confirm the entry exists:
+
+```bash
+sessionmem install
+sessionmem stats   # check the session_events counter after a few tool calls
+```
+
+To watch the hook work in real time, run your host with `SESSIONMEM_DEBUG=1`; the hook then reports each ingest to stderr, including the project id it wrote to.
+
+### Memory is keyed to the repository
+
+A project's memories are keyed by its **repository root**, the nearest directory containing `.git`. All subdirectories in one repository share the same memory bucket.
+
+Outside a repository, the id falls back to the exact working directory. Two different directories that are not in a repository are two different projects, so running `sessionmem stats` from a different folder than the one your host session used will show an empty store. Either run from inside the repository, or pin the id explicitly:
+
+```bash
+export SESSIONMEM_PROJECT_ID=my-project
+```
+
+Use `sessionmem browse` to list every project that has memories along with its id; the current project is marked.
+
+### Not enough events to summarize
+
+`handleSessionEnd` only writes a session summary once at least 3 events were captured. A very short session is skipped by design and reports `not enough session events to summarize`.
+
+## `better-sqlite3` native-build failures
+
+`sessionmem` stores memories in SQLite via `better-sqlite3`, which is a **native** module compiled for your platform and Node version. Most install-time crashes come from this native build.
+
+### node-gyp build errors
+
+If `npm install` fails compiling `better-sqlite3` with `node-gyp` errors, your toolchain is incomplete:
+
+- **Windows**: install the Visual Studio Build Tools (MSVC C++ workload). `node-gyp` needs an MSVC compiler; without it the native build fails.
+- **macOS**: install the Xcode Command Line Tools (`xcode-select --install`).
+- **Linux**: install `build-essential` (or your distro's equivalent: a C/C++ compiler, `make`, and `python3`).
+
+### ABI mismatch (Node 20 vs 22)
+
+`better-sqlite3` is compiled against a specific Node ABI. If you switch Node versions (for example from Node 20 to Node 22), a prebuilt or previously compiled binary can fail to load with a module-version / ABI mismatch error. Rebuild the native module against your current Node by reinstalling, or run `npm rebuild better-sqlite3`. If you use a Node version manager, make sure you reinstall after switching versions.
+
+### Confirming the build
+
+After a successful build, `sessionmem stats` (or any command that touches the database) will run without a native-load error. A native-build failure typically surfaces immediately as a "cannot find module" or "was compiled against a different Node.js version" error the first time the database is opened.

package/docs/typescript-upgrade.md

@@ -0,0 +1,48 @@
+# TypeScript 7 upgrade status
+
+The supported development toolchain currently uses TypeScript 6.0.3. Do not
+force TypeScript 7 into the dependency tree or disable peer dependency checks.
+This is a tooling compatibility issue, not an application type error.
+
+## Why Dependabot PR #21 fails
+
+PR #21 upgrades `typescript` from 6.0.3 to 7.0.2. On every CI platform, `npm ci`
+fails with `ERESOLVE` before lint, typecheck, build, or tests run:
+
+- The PR's typescript-eslint 8.62.1 requires `typescript >=4.8.4 <6.1.0`.
+- The latest published typescript-eslint checked for this review, 8.71.2,
+  still has that peer requirement. Updating the linter alone does not fix it.
+- A separate scratch installation forced to TypeScript 7.0.2 plus
+  typescript-eslint 8.71.2 fails on import with
+  `Error: typescript-eslint does not support TS 7.0.`
+- TypeScript 7's root export provides version information, not the previous
+  compiler API: `createSourceFile` and `SyntaxKind` are both undefined.
+  The new `typescript/unstable/*` APIs are not drop-in replacements for tools
+  that consume TypeScript 6's API.
+
+The standalone TypeScript 7.0.2 compiler successfully typechecks this repository
+with `tsc --noEmit -p tsconfig.json`. That does not make the whole toolchain
+compatible: ESLint imports typescript-eslint from `eslint.config.mjs`, so bypassing
+npm's peer checks still leaves lint broken. No application or tsconfig change
+can supply the missing upstream API.
+
+## Upgrade criteria
+
+Keep TypeScript 6 until typescript-eslint explicitly supports the selected
+TypeScript 7 release and its import/parser work with that compiler. Dependabot
+continues TypeScript 6 updates; TypeScript 7+ version updates are temporarily
+ignored to avoid recreating a known failing PR. Remove that ignore when support
+lands, update TypeScript and typescript-eslint together, regenerate the lockfile
+with normal peer resolution, and run:
+
+```bash
+npm ci
+npm run build
+npm run typecheck
+npm run lint
+npm test
+```
+
+All CI operating systems and Node versions, including packaged-install smoke
+tests and the security job, must pass before accepting the upgrade. Revisit
+[PR #21](https://github.com/catfish-1234/sessionmem/pull/21) at that point.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionmem",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "private": false,
   "type": "module",
   "description": "Local-first MCP memory layer for coding agents across Claude Code, Codex, Cursor, Cline, Windsurf, and other MCP-compatible hosts.",
@@ -12,7 +12,12 @@
   },
   "mcpName": "io.github.catfish-1234/sessionmem",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    ".github/sessionmem-logo.svg"
   ],
   "publishConfig": {
     "access": "public"
@@ -28,24 +33,31 @@
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "benchmark": "node scripts/benchmark.mjs",
-    "version": "node scripts/sync-version.mjs && git add package/package.json .claude-plugin/plugin.json server.json",
+    "version": "node scripts/sync-version.mjs && git add package/package.json .claude-plugin/plugin.json server.json Dockerfile",
     "postversion": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.107.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.4.1",
-    "commander": "^15.0.0",
+    "@anthropic-ai/sdk": "^0.135.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "better-sqlite3": "^12.11.1",
+    "commander": "^14.0.3",
     "js-tiktoken": "^1.0.21",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "eslint": "^10.4.1",
-    "globals": "^17.6.0",
+    "@types/better-sqlite3": "^9.6.0",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.0",
+    "typescript-eslint": "^8.71.2",
     "vitest": "^4.1.8"
-  }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  },
+  "bugs": {
+    "url": "https://github.com/catfish-1234/sessionmem/issues"
+  },
+  "homepage": "https://github.com/catfish-1234/sessionmem#readme"
 }