supamem 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. supamem-0.1.1/.github/workflows/ci.yml +26 -0
  2. supamem-0.1.1/.github/workflows/release.yml +76 -0
  3. supamem-0.1.1/.gitignore +9 -0
  4. supamem-0.1.1/AGENTS.md +116 -0
  5. supamem-0.1.1/CHANGELOG.md +99 -0
  6. supamem-0.1.1/CLAUDE.md +43 -0
  7. supamem-0.1.1/LICENSE +21 -0
  8. supamem-0.1.1/MIGRATION.md +45 -0
  9. supamem-0.1.1/PKG-INFO +408 -0
  10. supamem-0.1.1/README.md +380 -0
  11. supamem-0.1.1/llms.txt +51 -0
  12. supamem-0.1.1/pyproject.toml +62 -0
  13. supamem-0.1.1/src/supamem/__init__.py +2 -0
  14. supamem-0.1.1/src/supamem/__main__.py +4 -0
  15. supamem-0.1.1/src/supamem/cli.py +267 -0
  16. supamem-0.1.1/src/supamem/config.py +168 -0
  17. supamem-0.1.1/src/supamem/config_io.py +227 -0
  18. supamem-0.1.1/src/supamem/console.py +116 -0
  19. supamem-0.1.1/src/supamem/doctor.py +201 -0
  20. supamem-0.1.1/src/supamem/embedders/__init__.py +33 -0
  21. supamem-0.1.1/src/supamem/embedders/bm25.py +26 -0
  22. supamem-0.1.1/src/supamem/embedders/minilm.py +22 -0
  23. supamem-0.1.1/src/supamem/eval/__init__.py +22 -0
  24. supamem-0.1.1/src/supamem/eval/auto_goldens.py +70 -0
  25. supamem-0.1.1/src/supamem/eval/goldens/__init__.py +0 -0
  26. supamem-0.1.1/src/supamem/eval/goldens/phase_80_1_tuned_hybrid.jsonl +33 -0
  27. supamem-0.1.1/src/supamem/eval/runner.py +159 -0
  28. supamem-0.1.1/src/supamem/hooks/__init__.py +31 -0
  29. supamem-0.1.1/src/supamem/hooks/claude_code.py +217 -0
  30. supamem-0.1.1/src/supamem/hooks/cursor.py +194 -0
  31. supamem-0.1.1/src/supamem/hooks/opencode.py +30 -0
  32. supamem-0.1.1/src/supamem/indexer/__init__.py +179 -0
  33. supamem-0.1.1/src/supamem/indexer/chunker.py +69 -0
  34. supamem-0.1.1/src/supamem/indexer/manifest.py +56 -0
  35. supamem-0.1.1/src/supamem/init.py +214 -0
  36. supamem-0.1.1/src/supamem/install/__init__.py +98 -0
  37. supamem-0.1.1/src/supamem/install/_types.py +13 -0
  38. supamem-0.1.1/src/supamem/install/claude_code.py +211 -0
  39. supamem-0.1.1/src/supamem/install/cursor.py +178 -0
  40. supamem-0.1.1/src/supamem/install/opencode.py +136 -0
  41. supamem-0.1.1/src/supamem/install/share.py +74 -0
  42. supamem-0.1.1/src/supamem/mcp_server.py +259 -0
  43. supamem-0.1.1/src/supamem/migrate.py +214 -0
  44. supamem-0.1.1/src/supamem/retrieval/__init__.py +22 -0
  45. supamem-0.1.1/src/supamem/retrieval/bm25.py +21 -0
  46. supamem-0.1.1/src/supamem/retrieval/dense.py +37 -0
  47. supamem-0.1.1/src/supamem/retrieval/tuned_hybrid.py +203 -0
  48. supamem-0.1.1/src/supamem/retrieval/types.py +20 -0
  49. supamem-0.1.1/src/supamem/share/__init__.py +0 -0
  50. supamem-0.1.1/src/supamem/share/commands/__init__.py +0 -0
  51. supamem-0.1.1/src/supamem/share/commands/sm-search.md +33 -0
  52. supamem-0.1.1/src/supamem/share/cursor-rules/__init__.py +0 -0
  53. supamem-0.1.1/src/supamem/share/cursor-rules/dual-memory.mdc +33 -0
  54. supamem-0.1.1/src/supamem/share/hooks/__init__.py +0 -0
  55. supamem-0.1.1/src/supamem/share/hooks/qdrant-semantic-guard.sh +36 -0
  56. supamem-0.1.1/src/supamem/share/rules/__init__.py +0 -0
  57. supamem-0.1.1/src/supamem/share/rules/dual-memory.md +49 -0
  58. supamem-0.1.1/src/supamem/share/skills/__init__.py +0 -0
  59. supamem-0.1.1/src/supamem/share/skills/supamem/SKILL.md +41 -0
  60. supamem-0.1.1/src/supamem/share/skills/supamem/__init__.py +0 -0
  61. supamem-0.1.1/src/supamem/stats/__init__.py +99 -0
  62. supamem-0.1.1/src/supamem/stats/counter.py +138 -0
  63. supamem-0.1.1/src/supamem/update_check.py +249 -0
  64. supamem-0.1.1/tests/__init__.py +0 -0
  65. supamem-0.1.1/tests/test_chunker.py +68 -0
  66. supamem-0.1.1/tests/test_cli_smoke.py +80 -0
  67. supamem-0.1.1/tests/test_config_discovery.py +125 -0
  68. supamem-0.1.1/tests/test_config_io.py +147 -0
  69. supamem-0.1.1/tests/test_console.py +107 -0
  70. supamem-0.1.1/tests/test_counter.py +121 -0
  71. supamem-0.1.1/tests/test_doctor.py +111 -0
  72. supamem-0.1.1/tests/test_eval_runner.py +136 -0
  73. supamem-0.1.1/tests/test_hook_claude_code.py +174 -0
  74. supamem-0.1.1/tests/test_hook_cursor.py +157 -0
  75. supamem-0.1.1/tests/test_indexer.py +189 -0
  76. supamem-0.1.1/tests/test_init.py +93 -0
  77. supamem-0.1.1/tests/test_install_claude_code.py +109 -0
  78. supamem-0.1.1/tests/test_install_cursor.py +98 -0
  79. supamem-0.1.1/tests/test_install_opencode.py +77 -0
  80. supamem-0.1.1/tests/test_mcp_server.py +184 -0
  81. supamem-0.1.1/tests/test_migrate.py +145 -0
  82. supamem-0.1.1/tests/test_tuned_hybrid.py +141 -0
  83. supamem-0.1.1/tests/test_update_check.py +331 -0
@@ -0,0 +1,26 @@
1
+ name: ci
2
+ on:
3
+ push:
4
+ branches: [main]
5
+ pull_request:
6
+
7
+ jobs:
8
+ test:
9
+ runs-on: ubuntu-latest
10
+ strategy:
11
+ matrix:
12
+ python-version: ["3.12"]
13
+ # - "3.13" # add when GH runners stable
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: ${{ matrix.python-version }}
19
+ - name: Install package
20
+ run: |
21
+ python -m pip install --upgrade pip
22
+ pip install -e .[dev]
23
+ - name: Lint
24
+ run: ruff check src/supamem
25
+ - name: Test
26
+ run: pytest tests/ -v
@@ -0,0 +1,76 @@
1
+ name: release
2
+
3
+ on:
4
+ push:
5
+ tags: ['v*']
6
+
7
+ jobs:
8
+ build:
9
+ name: Build wheel + sdist
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ with:
14
+ fetch-depth: 0
15
+
16
+ - name: Set up Python
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+
21
+ - name: Install build + twine
22
+ run: pip install build twine
23
+
24
+ - name: Build
25
+ run: python -m build
26
+
27
+ - name: Twine check
28
+ run: twine check dist/*
29
+
30
+ - name: List artifacts
31
+ run: ls -lh dist/
32
+
33
+ - name: Upload dist artifact
34
+ uses: actions/upload-artifact@v4
35
+ with:
36
+ name: dist
37
+ path: dist/
38
+
39
+ publish-pypi:
40
+ name: Publish to PyPI (Trusted Publisher OIDC)
41
+ needs: build
42
+ runs-on: ubuntu-latest
43
+ environment:
44
+ name: pypi
45
+ url: https://pypi.org/p/supamem
46
+ permissions:
47
+ id-token: write
48
+ steps:
49
+ - name: Download dist artifact
50
+ uses: actions/download-artifact@v4
51
+ with:
52
+ name: dist
53
+ path: dist/
54
+
55
+ - name: Publish to PyPI
56
+ uses: pypa/gh-action-pypi-publish@release/v1
57
+
58
+ github-release:
59
+ name: Create GitHub release
60
+ needs: build
61
+ runs-on: ubuntu-latest
62
+ permissions:
63
+ contents: write
64
+ steps:
65
+ - name: Download dist artifact
66
+ uses: actions/download-artifact@v4
67
+ with:
68
+ name: dist
69
+ path: dist/
70
+
71
+ - name: Create GitHub release
72
+ uses: softprops/action-gh-release@v2
73
+ with:
74
+ files: dist/*
75
+ generate_release_notes: true
76
+ fail_on_unmatched_files: true
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .pytest_cache/
4
+ .ruff_cache/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .venv/
9
+ .coverage
@@ -0,0 +1,116 @@
1
+ # AGENTS.md — supamem
2
+
3
+ Operational guide for AI coding agents working in this repository. Project-agnostic dual-memory CLI for Claude Code, Cursor, and OpenCode.
4
+
5
+ ## Project Snapshot
6
+
7
+ - **Language:** Python 3.12+
8
+ - **Build backend:** hatchling
9
+ - **Package manager:** `uv`
10
+ - **CLI entry:** `supamem` → `src/supamem/cli.py:main`
11
+ - **Tests:** `pytest` (config in `pyproject.toml`)
12
+ - **Lint/format:** `ruff` (line length 100, target py312)
13
+ - **External deps:** Qdrant 1.10+ (HTTP), MCP 1.13+, fastembed, langchain-text-splitters
14
+
15
+ ## Architecture
16
+
17
+ ```
18
+ src/supamem/
19
+ ├── cli.py # Typer-based CLI dispatcher
20
+ ├── console.py # Shared Rich console + theme (single source of branding)
21
+ ├── config.py # Pydantic config schema (D-38)
22
+ ├── config_io.py # Discovery: project → user → defaults; merge order locked
23
+ ├── doctor.py # Health + drift report (Plan 80.6-11)
24
+ ├── init.py # Greenfield bootstrap (Plan 80.6-08)
25
+ ├── migrate.py # Brownfield migration paths (Plan 80.6-09)
26
+ ├── mcp_server.py # MCP server entrypoint
27
+ ├── embedders/ # minilm, bm25 — pluggable via entry-points
28
+ ├── indexer/ # chunker (markdown_header), manifest
29
+ ├── retrieval/ # tuned_hybrid, dense, bm25 backends
30
+ ├── eval/ # Bench runner + bundled goldens (Plan 80.6-12)
31
+ ├── hooks/ # claude_code, cursor — per-client snapshot hooks
32
+ ├── install/ # claude_code, cursor, opencode — config installers
33
+ ├── share/ # Canonical artifact templates
34
+ └── stats/ # Welford counter for usage telemetry
35
+ ```
36
+
37
+ ## Plugin Entry Points (D-48)
38
+
39
+ Three plugin groups in `pyproject.toml`. Third parties add backends without forking:
40
+
41
+ - `supamem.retrieval` — `tuned_hybrid`, `dense`, `bm25`
42
+ - `supamem.embedder` — `minilm`, `bm25`
43
+ - `supamem.chunker` — `markdown_header`
44
+
45
+ ## Config Discovery (D-38)
46
+
47
+ Order: `./.supamem/config.toml` (project) → `~/.config/supamem/config.toml` (user) → `share/default.toml` (shipped). Merge is shallow; project wins.
48
+
49
+ ## Hard Constraints
50
+
51
+ - NEVER bypass failing tests — fix root cause
52
+ - NEVER hardcode collection names; always read from `config.collection`
53
+ - NEVER print to stdout in MCP server — JSON-RPC contract requires stdio purity (use `err_console`)
54
+ - NEVER write to `~/` outside `~/.cache/supamem/` and `~/.config/supamem/` without explicit user opt-in
55
+ - NEVER delete a Qdrant collection without `--force` flag confirmation
56
+ - ALWAYS use `console.py` exports for terminal output (no bare `print()`)
57
+ - ALWAYS run `pytest` from project root via `uv run pytest`
58
+
59
+ ## Workflow
60
+
61
+ ```bash
62
+ # Setup
63
+ uv sync --extra dev
64
+
65
+ # Tests
66
+ uv run pytest # full suite
67
+ uv run pytest tests/test_X.py -v # single file
68
+
69
+ # Lint / type
70
+ uv run ruff check src tests
71
+ uv run ruff format src tests
72
+
73
+ # Build + verify
74
+ uv build
75
+ uvx twine check dist/*
76
+
77
+ # Run locally
78
+ uv run supamem --help
79
+ uv run python -m supamem doctor
80
+ ```
81
+
82
+ ## Test Discipline
83
+
84
+ - Subprocess-based CLI smoke tests (`test_cli_smoke.py`) MUST pin a deterministic env: `NO_COLOR=1`, `TERM=dumb`, `COLUMNS=200` — pop `FORCE_COLOR`. Rich autodetect alone is insufficient on CI runners.
85
+ - Use `pytest-asyncio` with `mode=Mode.STRICT`; mark async tests with `@pytest.mark.asyncio`.
86
+ - Mock Qdrant via fixtures, not by hitting a live instance — bench/eval suites are the integration boundary.
87
+
88
+ ## Release Process
89
+
90
+ 1. Bump `version` in `pyproject.toml` and add `CHANGELOG.md` entry.
91
+ 2. Verify license metadata complies with PEP 639 (`license = "MIT"` SPDX, no `License ::` classifier).
92
+ 3. `uv build && uvx twine check dist/*`
93
+ 4. Create annotated tag: `git tag -a vX.Y.Z -m "..."`
94
+ 5. Push tag: `git push origin vX.Y.Z` — release workflow publishes to PyPI via Trusted Publisher OIDC.
95
+ 6. Verify on PyPI: `pip install supamem==X.Y.Z` in a clean venv.
96
+
97
+ PyPI tags are immutable: never re-use a published version number.
98
+
99
+ ## Update-check (v0.1.1+)
100
+
101
+ A daemon thread probes GitHub Releases on every CLI invocation, caches result for 24h in `platformdirs.user_cache_dir("supamem")/update_check.json`, and prints a stderr footer on the *next* invocation if a newer version is available. Suppress with `SUPAMEM_NO_UPDATE_CHECK=1`, `CI=1`, or `NO_UPDATE_NOTIFIER=1`. Never blocks; never raises.
102
+
103
+ ## Reference Links
104
+
105
+ - README: high-level overview, install, quickstart
106
+ - MIGRATION.md: version-to-version upgrade notes
107
+ - CHANGELOG.md: release log
108
+ - `docs/` (if present): ADRs, design docs
109
+
110
+ ## Decision Guides
111
+
112
+ - New backend: register via entry-point group, do NOT modify `cli.py` dispatch
113
+ - New CLI subcommand: add Typer command in `cli.py`, route to module under `src/supamem/`
114
+ - New config field: extend `config.py` Pydantic schema + bump default in `share/default.toml`
115
+ - New hook target: add module under `src/supamem/hooks/<client>.py`, register in `cli.py hook` dispatcher
116
+ - Failure in network code: blanket `except Exception: pass` is correct for non-essential probes (update_check); for indexing/retrieval, surface error to user via `err_console`
@@ -0,0 +1,99 @@
1
+ # Changelog
2
+
3
+ All notable changes to `supamem` will be documented in this file.
4
+
5
+ ## v0.1.1 — 2026-04-29
6
+
7
+ First PyPI release. Hardens v0.1.0 with CI fixes, agent guides, an update-check
8
+ notifier, and a published wheel/sdist on PyPI so downstream consumers can pin a
9
+ version range instead of a git tag.
10
+
11
+ ### Added
12
+
13
+ - `supamem.update_check` — pip-style fire-and-forget GitHub Releases probe.
14
+ Daemon thread writes `platformdirs.user_cache_dir("supamem")/update_check.json`;
15
+ the *next* invocation prints a stderr footer if a newer release is cached.
16
+ 24h TTL, 6h backoff on 403/429, ETag-aware. Suppress with
17
+ `SUPAMEM_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, or `CI=1`. Skipped when
18
+ stderr is non-TTY. Surfaced in `supamem doctor` (new "Update check" section).
19
+ - `AGENTS.md` + `CLAUDE.md` — agent-facing project guides per the Apr 2026
20
+ cross-tool convention.
21
+
22
+ ### Changed
23
+
24
+ - License metadata migrated to PEP 639 SPDX expression (`license = "MIT"`),
25
+ removing legacy `{ text = "MIT" }` form.
26
+ - Distribution channel: PyPI (was git-tag-only). Install via
27
+ `pip install supamem` or `uv tool install supamem`.
28
+
29
+ ### Fixed
30
+
31
+ - `tests/test_cli_smoke.py` subprocess env now pins `NO_COLOR=1`, `TERM=dumb`,
32
+ `COLUMNS=200`, and pops `FORCE_COLOR` — eliminates Rich color escapes that
33
+ broke CI assertions on GitHub Actions runners.
34
+
35
+ ## v0.1.0 — 2026-04-29
36
+
37
+ The initial public release. Extracted from the SoftChat dual-memory stack
38
+ (Phases 80.1–80.5) and shipped as a project-agnostic Python package under MIT.
39
+
40
+ ### CLI surface (10 commands)
41
+
42
+ - `supamem init` — greenfield bootstrap (probes Qdrant, creates per-project
43
+ hybrid collection, writes `.supamem/config.toml`).
44
+ - `supamem install --client {claude-code|cursor|opencode}` — patches the
45
+ client config atomically; idempotent; `--dry-run` supported.
46
+ - `supamem uninstall --client X` — reverses install cleanly.
47
+ - `supamem index [--target tuned] [--force] [--snapshot cursor]` — embeds
48
+ Markdown sources into Qdrant or refreshes the Cursor `.mdc` snapshot.
49
+ - `supamem mcp-server [--transport stdio|http] [--port N] [--host H]` —
50
+ runs the MCP server. Streamable HTTP per Nov 2025 MCP spec (D-45).
51
+ - `supamem hook {claude-code|opencode} [--file-path X]` — per-client
52
+ PreToolUse hook delegate. Fail-soft: never blocks the calling tool.
53
+ - `supamem doctor [--show-secrets]` — health probe + resolved config chain
54
+ + version-drift advisory across detected clients.
55
+ - `supamem stats [--show today|week|all] [--format table|json]` — Welford
56
+ schema-v2 usage counters from `~/.cache/supamem/audit.jsonl`.
57
+ - `supamem migrate --source X --target Y --path {coexist|migrate|adopt-as-is}`
58
+ — brownfield migration with snapshot-before-destructive guard.
59
+ - `supamem eval [--regress] [--goldens path]` — recall@5 + p95 latency +
60
+ total tokens against the bundled 33-query corpus. Phase 80.1 baselines:
61
+ `mean_recall_at_5 >= 0.60`, `total_tokens <= 4000`, `p95_latency_ms <= 500`.
62
+
63
+ ### Bundled
64
+
65
+ - `~/.supamem/share/{rules,skills,commands,hooks,cursor-rules}/` — canonical
66
+ artifacts referenced by every client config (SC-3 reference-not-copy
67
+ contract; Cursor `.mdc` is the documented copy exception).
68
+ - 33-query golden corpus at `supamem.eval.goldens.phase_80_1_tuned_hybrid`
69
+ for `--regress` (per D-46).
70
+ - Plugin entry-point groups for retrieval, embedder, and chunker so
71
+ third-party packages can extend supamem without forking (per D-48).
72
+
73
+ ### Locked architecture (Phase 80.1 D-19 / D-25)
74
+
75
+ - Hybrid retrieval: BM25 (`Qdrant/bm25`) + dense (`sentence-transformers/
76
+ all-MiniLM-L6-v2`) with Qdrant native `FusionQuery(RRF)`, prefetch=20.
77
+ - T-1 markdown header chunker, soft-max 250 tokens, fallback 200/20.
78
+ - T-4 recency boost, T-5 cosine dedup (threshold 0.97), T-8 token-budget
79
+ truncation (1500).
80
+
81
+ ### Install
82
+
83
+ ```bash
84
+ uv tool install git+https://github.com/dzmitrys-dev/supamem@v0.1.0
85
+ ```
86
+
87
+ PyPI publish is deferred to v0.2 per D-44. v0.1.0 is git-tag-only so
88
+ SoftChat's rip-out commit (Plan 80.6-14) can pin a verifiable artifact
89
+ before the broader package distribution surface lands.
90
+
91
+ ### Notes
92
+
93
+ - Forward-compat: tool `title` field set on every MCP tool registration;
94
+ Cursor / Claude.ai web honor it today; Claude Code TUI ignores but will
95
+ pick up automatically when the upstream lands.
96
+ - Stylish `rich`-powered CLI output (banner, panels, spinners, status
97
+ tables) on every long-running command.
98
+ - Made with care by [SoftChat](https://app.softchat.ru) and
99
+ [SoftSkillz](https://softskillz.ai).
@@ -0,0 +1,43 @@
1
+ # CLAUDE.md — supamem
2
+
3
+ Claude Code instructions for the supamem repository.
4
+
5
+ @AGENTS.md
6
+
7
+ ## Workflow
8
+
9
+ - Use `/brainstorm` before ambiguous feature work
10
+ - Use `/write-plan` before multi-step implementation
11
+ - Use `/systematic-debug` before proposing bug fixes
12
+ - Verify with `uv run pytest` (project root) and `uv run ruff check src tests` before claiming done
13
+
14
+ ## Hard Constraints
15
+
16
+ - NEVER use bare `print()` — import from `src/supamem/console.py`
17
+ - NEVER print to stdout from `mcp_server.py` — JSON-RPC purity (use `err_console`)
18
+ - NEVER hardcode collection names — read `config.collection`
19
+ - NEVER skip the PEP 639 license check on release — `license = "MIT"` SPDX, no `License ::` classifier
20
+ - NEVER force-move a published git tag — PyPI rejects re-uploads of the same version
21
+ - NEVER suppress errors in indexing/retrieval paths — surface via `err_console`
22
+ - Update-check is the ONLY code path where blanket `except Exception: pass` is acceptable
23
+
24
+ ## Definition Of Done
25
+
26
+ - `uv run pytest` green (full suite)
27
+ - `uv run ruff check src tests` clean
28
+ - New CLI subcommand: smoke test in `tests/test_cli_smoke.py`
29
+ - New backend: registered via entry-point, covered by unit + integration test
30
+ - Release: `uv build && uvx twine check dist/*` clean before tagging
31
+
32
+ ## Critical Config
33
+
34
+ - Config discovery order: `.supamem/config.toml` → `~/.config/supamem/config.toml` → `share/default.toml`
35
+ - Cache dir: `platformdirs.user_cache_dir("supamem")` — never `~/.cache/supamem` directly
36
+ - CI env: smoke tests pin `NO_COLOR=1`, `TERM=dumb`, `COLUMNS=200`, pop `FORCE_COLOR`
37
+
38
+ ## When Blocked
39
+
40
+ - Test fails on CI but passes locally: check Rich color escape pollution (see test_cli_smoke env override)
41
+ - Import error: confirm `uv sync --extra dev` ran; check entry-points in `pyproject.toml`
42
+ - Qdrant connection failure: `docker compose up qdrant` or use mock fixture
43
+ - 2+ verification failures: stop and report blocker with command output
supamem-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dzmitrys-dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,45 @@
1
+ # Migration
2
+
3
+ ## v0.1.0 (initial release)
4
+
5
+ First public release. No upgrade path required — install via:
6
+
7
+ ```bash
8
+ uv tool install git+https://github.com/dzmitrys-dev/supamem@v0.1.0
9
+ ```
10
+
11
+ ### Plugin entry-point contract (D-48)
12
+
13
+ `supamem` exposes three plugin groups via `pyproject.toml`
14
+ `[project.entry-points]`. Third-party packages can register additional
15
+ backends without forking:
16
+
17
+ ```toml
18
+ [project.entry-points."supamem.retrieval"]
19
+ my_backend = "my_pkg.backend:MyBackend"
20
+
21
+ [project.entry-points."supamem.embedder"]
22
+ my_dense = "my_pkg.embedders:MyDenseEmbedder"
23
+
24
+ [project.entry-points."supamem.chunker"]
25
+ my_chunker = "my_pkg.chunker:my_chunk_fn"
26
+ ```
27
+
28
+ **Compatibility caveat (v0):** the plugin contract is _unstable_ until v1.
29
+ A `0.x.y` minor bump may break plugins. Pin against `supamem==0.1.*` in
30
+ your plugin's `requirements`. The shape of `RetrievedChunk`, the
31
+ `Backend.query(text, k)` signature, and entry-point group names are the
32
+ load-bearing surface; everything else may move.
33
+
34
+ The built-in registrations (`tuned_hybrid`, `dense`, `bm25` for retrieval;
35
+ `minilm`, `bm25` for embedder; `markdown_header` for chunker) are part of
36
+ the wheel and resolve automatically via `importlib.metadata.entry_points`.
37
+
38
+ ## SoftChat -> supamem migration
39
+
40
+ _(Filled in by Phase 80.6 plan 14: SoftChat rip-out.)_
41
+
42
+ This section will document the exact steps SoftChat took to replace its in-tree
43
+ `scripts/embed-dev-memories.py`, `scripts/dual_memory_mcp_server.py`,
44
+ `scripts/dual_memory_bootstrap.py`, `scripts/dm_counter_bump.py`, and
45
+ `scripts/regen_cursor_dual_memory_rule.py` with the `supamem` binary.