sessionmem 1.3.0 → 1.5.0

package/.github/sessionmem-logo.svg

@@ -0,0 +1,57 @@
+<svg width="680" height="310" viewBox="0 0 680 310" xmlns="http://www.w3.org/2000/svg" role="img">
+  <title>sessionmem</title>
+  <desc>Catfish mascot for sessionmem -- stylized catfish with teal eye and memory circuit dots on barbels</desc>
+
+  <!-- Tail upper fork -->
+  <path d="M 248,145 C 225,125 198,106 172,88 C 190,102 214,126 248,145" fill="#0f172a"/>
+  <!-- Tail lower fork -->
+  <path d="M 248,145 C 225,165 198,184 172,202 C 190,189 214,166 248,145" fill="#0f172a"/>
+  <!-- Tail fill -->
+  <path d="M 248,145 L 190,108 L 190,182 Z" fill="#0f172a"/>
+
+  <!-- Main body -->
+  <ellipse cx="380" cy="145" rx="138" ry="82" fill="#0f172a"/>
+
+  <!-- Belly highlight -->
+  <ellipse cx="386" cy="172" rx="104" ry="46" fill="#1a3454"/>
+
+  <!-- Dorsal fin -->
+  <path d="M 338,63 C 358,28 402,22 418,63" fill="#152840"/>
+
+  <!-- Pectoral fin -->
+  <path d="M 430,222 C 450,248 468,252 454,234 C 445,220 430,222 430,222" fill="#152840"/>
+
+  <!-- Lateral line -->
+  <path d="M 265,138 Q 340,130 420,132 Q 462,132 495,140" stroke="#1e3a5f" stroke-width="1.5" fill="none"/>
+
+  <!-- Eye glow -->
+  <circle cx="470" cy="116" r="30" fill="#0d9488" opacity="0.18"/>
+  <!-- Eye -->
+  <circle cx="470" cy="116" r="22" fill="#0d9488"/>
+  <!-- Pupil -->
+  <circle cx="470" cy="116" r="11" fill="#081120"/>
+  <!-- Eye shine -->
+  <circle cx="477" cy="109" r="5" fill="#ccfbf1"/>
+
+  <!-- Barbels from mouth -->
+  <path d="M 518,131 C 540,120 558,110 566,97" stroke="#3d5270" stroke-width="2.8" fill="none" stroke-linecap="round"/>
+  <path d="M 518,142 C 546,142 565,143 578,145" stroke="#3d5270" stroke-width="2.8" fill="none" stroke-linecap="round"/>
+  <path d="M 518,153 C 538,167 552,183 555,198" stroke="#3d5270" stroke-width="2.8" fill="none" stroke-linecap="round"/>
+
+  <!-- Memory circuit dots at barbel tips -->
+  <circle cx="566" cy="97" r="7" fill="#2dd4bf"/>
+  <circle cx="578" cy="145" r="7" fill="#2dd4bf"/>
+  <circle cx="555" cy="198" r="7" fill="#2dd4bf"/>
+
+  <!-- Floating memory dots -->
+  <circle cx="608" cy="90" r="5" fill="#2dd4bf" opacity="0.6"/>
+  <circle cx="632" cy="75" r="3.5" fill="#2dd4bf" opacity="0.42"/>
+  <circle cx="626" cy="118" r="4.5" fill="#2dd4bf" opacity="0.5"/>
+  <circle cx="651" cy="100" r="3" fill="#2dd4bf" opacity="0.3"/>
+
+  <!-- Wordmark -->
+  <text x="340" y="278" text-anchor="middle"
+        font-family="'Courier New', Courier, monospace"
+        font-size="42" font-weight="500" letter-spacing="-1"
+        fill="#0d9488">sessionmem</text>
+</svg>

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.5.0] - 2026-10-18
+
+### Added
+
+- `sessionmem scan` to import existing Claude Code transcripts into memory, and
+  `sessionmem watch` to capture new and updated sessions continuously. Both are
+  idempotent across reruns and restarts and work fully offline. ([#45])
+- Automatic host detection during `sessionmem install`, and a `sessionmem doctor`
+  command that checks the store, hooks, adapter wiring, and recall with fix
+  hints for each failure. ([#46])
+- Deterministic entity and relation extraction during capture and scan, a
+  `sessionmem entities` command, and entity overlap as a recall ranking
+  signal. ([#48])
+- Deterministic supersession handling: memories that replace an earlier fact are
+  linked with history, and recall prefers current facts while replaced ones stay
+  retrievable explicitly. ([#49])
+- `sessionmem ui`, a local read-only web viewer for memories, entities,
+  relations, and supersession history, served on localhost with no external
+  services. ([#50])
+- COMPARISON.md, a cited comparison with claude-mem, Mem0, and Zep, plus a draft
+  MCP registry listing. ([#51])
+- A reproducible offline LoCoMo evaluation: committed corpus with provenance and
+  checksums, and a runner reporting hit rate, precision, recall, and latency
+  with all network access blocked. ([#44])
+
+### Changed
+
+- Retrieval now ranks with SQLite FTS5 BM25 and Porter stemming over memory
+  content and summaries. Measured on the committed LoCoMo evaluation, top-5 hit
+  rate improved from 1.44% to 61.95%, and to 63.92% with entity overlap. ([#47], [#48])
+- The release workflow skips the npm publish when the version already exists on
+  the registry and creates the GitHub release with notes from this
+  changelog. ([#43])
+
+## [1.4.0] - 2026-10-16
+
+### Added
+
+- A `SECURITY.md` policy covering supported releases, private vulnerability
+  reporting through GitHub security advisories, and response expectations. ([#31])
+- Bug report and pull request templates, with private security reporting guidance. ([#40])
+- Documentation of the TypeScript 7 toolchain blocker and criteria for revisiting
+  the upgrade. ([#33])
+- Package homepage and issue tracker metadata, and bundled documentation,
+  changelog, contribution and security policies, and the README logo in the npm
+  package. ([#34], [#40])
+
+### Changed
+
+- Aligned supported Node.js versions to `^20.19.0 || >=22.13.0`, using Commander
+  14.0.3 to retain Node 20 compatibility. Deferred better-sqlite3 13 and Vitest 5,
+  and temporarily ignored TypeScript 7+ updates until the toolchain supports them. ([#33], [#34])
+- Updated compatible runtime and development dependencies, including the Anthropic
+  and MCP SDKs, better-sqlite3, Zod, ESLint, typescript-eslint, globals, and SQLite
+  types; upgraded the setup-node action. ([#22], [#23], [#24], [#28], [#34])
+- Clarified installation, adapter selection, Claude Code lifecycle hooks versus
+  other MCP hosts, local database checks, command limits, import behavior,
+  environment overrides, cloud fallback, and migration guidance in the README,
+  CLI help, and linked documentation. The development MCP template now runs the
+  local build, and the `llms.txt` example includes the required `run` argument. ([#34], [#40])
+
+### Fixed
+
+- Database path overrides now create only the selected database's parent
+  directories, without creating `~/.sessionmem`. Server logs stay beside that
+  database, and in-memory databases do not create log directories. ([#40])
+- Null and other invalid import records are skipped with warnings instead of
+  crashing; imports preserve provenance and original record indices. UTF-8 BOM
+  and CRLF files are accepted, and invalid UTF-8 is rejected. Null or non-object
+  policy configuration safely falls back to defaults. ([#40])
+- Token caps now account for truncation markers and enforce actual token counts,
+  including large-session summaries and cloud summarization output. ([#40])
+- Concurrent SQLite WAL initialization retries within a bounded five-second wait;
+  migration checks and writes are serialized, and failed database initialization
+  closes its handle. ([#40])
+- Malformed numeric search limits and deduplication thresholds are rejected.
+  Search consistently defaults to 10 results, and memory lists warn when the
+  200-record limit truncates their output. ([#40])
+- CLI install, uninstall, and default-export tests use temporary home directories;
+  project-root fixtures no longer depend on whether the temporary directory is
+  inside another repository. ([#30])
+- The mirrored package manifest and Docker install pin stay synchronized with
+  release versions and runtime dependency metadata. ([#34])
+- The release workflow installs dependencies, builds, and tests before upgrading
+  npm for trusted publishing, preserving better-sqlite3's native install step.
+  ([62765a7])
+
+### Security
+
+- Refreshed vulnerable transitive dependencies, including `proxy-addr` 2.0.8 and
+  `fast-uri` 3.1.8, with MCP SDK 1.32.1, removing the reported critical and moderate
+  advisories without suppressing findings. ([#27], [#29])
+- Pinned every GitHub Action in CI, release, and security workflows to a verified
+  full commit SHA. Replaced the retired Semgrep action with CLI 1.181.0 so scanner
+  errors and findings fail the job; added scanner dependency updates and
+  Dependabot cooldowns. ([#32])
+
+[1.5.0]: https://github.com/catfish-1234/sessionmem/compare/679b8954f0b49f197985c40da47f181c00060cd9...v1.5.0
+[#43]: https://github.com/catfish-1234/sessionmem/pull/43
+[#44]: https://github.com/catfish-1234/sessionmem/pull/44
+[#45]: https://github.com/catfish-1234/sessionmem/pull/45
+[#46]: https://github.com/catfish-1234/sessionmem/pull/46
+[#47]: https://github.com/catfish-1234/sessionmem/pull/47
+[#48]: https://github.com/catfish-1234/sessionmem/pull/48
+[#49]: https://github.com/catfish-1234/sessionmem/pull/49
+[#50]: https://github.com/catfish-1234/sessionmem/pull/50
+[#51]: https://github.com/catfish-1234/sessionmem/pull/51
+[1.4.0]: https://github.com/catfish-1234/sessionmem/compare/a73f503123b1d33c35407ce66403f281ba3451ac...679b8954f0b49f197985c40da47f181c00060cd9
+[#22]: https://github.com/catfish-1234/sessionmem/pull/22
+[#23]: https://github.com/catfish-1234/sessionmem/pull/23
+[#24]: https://github.com/catfish-1234/sessionmem/pull/24
+[#27]: https://github.com/catfish-1234/sessionmem/pull/27
+[#28]: https://github.com/catfish-1234/sessionmem/pull/28
+[#29]: https://github.com/catfish-1234/sessionmem/pull/29
+[#30]: https://github.com/catfish-1234/sessionmem/pull/30
+[#31]: https://github.com/catfish-1234/sessionmem/pull/31
+[#32]: https://github.com/catfish-1234/sessionmem/pull/32
+[#33]: https://github.com/catfish-1234/sessionmem/pull/33
+[#34]: https://github.com/catfish-1234/sessionmem/pull/34
+[#40]: https://github.com/catfish-1234/sessionmem/pull/40
+[62765a7]: https://github.com/catfish-1234/sessionmem/commit/62765a7

package/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to sessionmem
+
+To work on sessionmem, clone the repository, install dependencies, and build it using the commands below.
+
+## Getting started
+
+```bash
+git clone https://github.com/catfish-1234/sessionmem.git
+cd sessionmem
+npm ci
+npm run build
+```
+
+### MCP config for local development
+
+Copy `.mcp.json.example` to `.mcp.json` and replace its example path with the
+absolute path to this checkout’s `dist/cli/index.js`. Rebuild after source changes.
+`sessionmem install` registers the executable on PATH, which may be a different
+installed version. The `.mcp.json` file is gitignored because it contains machine-specific paths.
+
+## Development workflow
+
+Use Node 20.19+ or 22.13+ (Node 22 LTS recommended). Commander stays on 14
+because 15 requires Node 22.12+, while this project still tests Node 20.
+Likewise, better-sqlite3 13 and Vitest 5 require Node 22; those major upgrades
+are deferred until the Node support policy changes. Compatible dependency
+updates remain enabled.
+
+### Build
+
+```bash
+npm run build        # compile TypeScript + copy migrations
+```
+
+### Test
+
+```bash
+npm test             # run all tests (Vitest)
+npm run test:schema  # run schema/migration tests only
+```
+
+### Lint and typecheck
+
+```bash
+npm run lint         # ESLint
+npm run typecheck    # tsc --noEmit
+```
+
+See [TypeScript 7 upgrade status](docs/typescript-upgrade.md) for the current
+upstream tooling blocker and the criteria for removing the temporary Dependabot ignore.
+
+### Benchmarks
+
+```bash
+npm run build        # benchmarks import from dist/
+npm run benchmark    # regenerates docs/benchmark.md
+```
+
+All four checks (build, test, lint, typecheck) run in CI on Node 20 and 22 for
+Ubuntu and macOS, and Node 22 for Windows. CI also installs the npm tarball and
+checks the installed CLI. Run `npm pack --dry-run` to review published files;
+only compiled runtime files, migrations, and user documentation belong there.
+
+## Project structure
+
+```
+src/
+  core/       # Memory engine: storage, retrieval, ranking, summarization
+  adapters/   # MCP adapter layer (translates between MCP protocol and core)
+  cli/        # CLI commands (sessionmem install, search, etc.)
+tests/        # Vitest test suite
+scripts/      # Build helpers and benchmark runner
+docs/         # Architecture, benchmarks, and feature docs
+```
+
+## Code conventions
+
+- **TypeScript**: strict mode, ES2022 target, NodeNext module resolution.
+- **Unused vars**: prefix with underscore (`_unused`) to satisfy the lint rule.
+- **Explicit `any` in tests**: permitted in `tests/`; source code keeps the lint rule.
+- **Comments**: only when the "why" isn't obvious. No doc-block boilerplate.
+
+## Pre-commit hooks
+
+A [gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook runs automatically to prevent accidental secret commits. Install it with:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+## Submitting changes
+
+1. **Fork and branch**: create a feature branch from `main`.
+2. **Keep PRs focused**: one feature or fix per PR.
+3. **All checks must pass**: build, test, lint, and typecheck.
+4. **Write tests** for new functionality or bug fixes.
+5. **Update docs** if your change affects user-facing behavior or CLI commands.
+
+### Commit messages
+
+Use clear, descriptive commit messages. [Conventional Commits](https://www.conventionalcommits.org/) style is preferred:
+
+```
+feat: add memory export filtering by date range
+fix: handle empty project ID in search query
+docs: clarify team mode trust model
+chore: bump better-sqlite3 to v12.5
+```
+
+## Reporting bugs
+
+Open an issue with:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Node version, OS, and which MCP host you're using (Claude Code, Cursor, etc.)
+
+## Feature requests
+
+Open an issue describing the use case. Explain the problem you're trying to solve, not just the solution you have in mind.
+
+## Security
+
+If you find a security vulnerability, **do not open a public issue**. Use [GitHub private vulnerability reporting](https://github.com/catfish-1234/sessionmem/security/advisories/new). See the [security policy](SECURITY.md) for supported versions and response expectations, and the [security workflow](https://github.com/catfish-1234/sessionmem/blob/main/.github/workflows/security.yml) for automated scanning.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).