sessionmem 1.3.0 → 1.4.0

package/docs/team-mode.md

@@ -0,0 +1,117 @@
+# Team Mode (Shared Memory)
+
+Team mode shares `sessionmem` memories through a directory everyone on the team can read and write, such as a network drive or synced folder. With team mode enabled, `sessionmem sync` writes your local memories there and reads teammates' memories into your database. Your agent can then use decisions, warnings, and facts recorded by the team.
+
+Team mode is off by default. Enable it to start sharing.
+
+## Setup
+
+Enable team mode by pointing it at a shared directory:
+
+```
+sessionmem team enable <shared-path>
+```
+
+`<shared-path>` must be a directory that all teammates can read and write, typically a network share or a folder synced across machines. The path is recorded in `~/.sessionmem/config.json` under the `team` section (`team.enabled` / `team.sharedPath`).
+
+Inside the shared path, `sessionmem` uses a per-project, per-user file layout:
+
+```
+{sharedPath}/{project_id}/{username}.json
+```
+
+Each teammate writes one snapshot file named after their OS username. Each project has its own subdirectory to keep snapshots separate.
+
+To check the current state:
+
+```
+sessionmem team status
+```
+
+This reports whether team mode is enabled and whether the shared path is reachable.
+
+## Usage: syncing
+
+Once team mode is enabled, run:
+
+```
+sessionmem sync
+```
+
+Each `sync` runs two steps:
+
+1. **Push**: writes a full snapshot of this project's local memories to
+   `{sharedPath}/{project_id}/{username}.json`. The write is atomic (a temp file
+   is written in the same directory and then renamed) so teammates don't read a
+   partly written snapshot.
+2. **Pull**: reads every other `*.json` snapshot in the project directory and
+   merges those memories into your local database.
+
+When it finishes, `sync` prints a summary:
+
+```
+Pushed N memories, pulled M new + updated K from teammates.
+```
+
+`N` is the number of local memories shared, `M` is the number of new teammate memories added, and `K` is the number of existing memories updated from teammate snapshots.
+
+If team mode is disabled, `sync` makes no changes and tells you to run `team enable` first.
+
+## Provenance and author annotation
+
+Each memory records its source:
+
+- **`author`**: the OS username of whoever created the memory.
+- **`created_at`**: when it was first created.
+
+In the agent's startup context, teammate memories have an `author:` prefix showing their recorded author, for example:
+
+```
+- [decision] alice: decided to use X (...)
+```
+
+Your own memories have no prefix. Older memories with an empty author also have no prefix. The prefix appears when the recorded author differs from your local username.
+
+## Conflict behavior
+
+When the same memory id exists locally and in a teammate's snapshot, `sync` resolves it as follows:
+
+- **Content**: sync uses last-write-wins by id, keeping the most recent content.
+- **Importance**: a teammate's snapshot cannot lower your local copy's importance score.
+- **Cross-project id collisions**: records whose ids already belong to a different project are skipped.
+- **Redaction**: every pulled record is checked again using your secret redaction policy.
+
+## Disable and recovery
+
+To stop syncing and keep memories already pulled from teammates:
+
+```
+sessionmem team disable
+```
+
+To also delete teammate-authored memories:
+
+```
+sessionmem team disable --remove-team-memories
+```
+
+This deletes the teammate-authored memories for this project, leaving only the memories you authored locally.
+
+## Trust boundary and security
+
+Anyone with write access to the shared path can add memories that your agent may use. Control access through the shared directory's filesystem permissions:
+
+- Restrict write access with OS filesystem permissions (ACLs) to the people you intend to share memories with.
+- The `author` field is advisory. A person with write access can change it, so the `author:` prefix does not verify identity.
+- `sessionmem` does not authenticate teammates, sign snapshots, or verify authorship. Enforce any additional access controls through the filesystem or file share.
+
+## Failure recovery
+
+When `sync` encounters filesystem or snapshot errors:
+
+- **Missing or unwritable shared path**: `sync` reports the error to stderr and
+  exits with a non-zero status. Your local memories are untouched.
+- **A corrupt or truncated teammate file**: the file is skipped with a warning,
+  and the rest of the pull continues.
+- **An invalid record inside an otherwise-valid file**: the record is skipped
+  with a warning; the remaining records still merge.

package/docs/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting
+
+This guide covers install failures, adapter (MCP host) issues, and `better-sqlite3` native-build failures. Configuration lives in `~/.sessionmem/config.json`.
+
+## 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` registers sessionmem with the MCP host in the current directory. If install reports that it could not find a host, you are likely running it outside a project the host recognizes. `cd` into your project root (where the host's config lives) and re-run `sessionmem install`. Use `sessionmem install --adapter <name>` from a plain terminal (for example `--adapter cline` or `--adapter windsurf`, which cannot be reliably auto-detected). Run `sessionmem ping` afterward to check local database access; it does not probe the host's MCP connection.
+
+### 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, confirm `sessionmem install` was run inside the project and that the MCP server entry exists in the host config. Use `sessionmem ping` to verify local database access, then check MCP connectivity in the host.
+- **Cursor**: Cursor must be pointed at the registered MCP server. Re-run `install` from the project root 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 ping` to check local database access, then check the host's MCP connection.
+
+## "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.4.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"
 }