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.
- supamem-0.1.1/.github/workflows/ci.yml +26 -0
- supamem-0.1.1/.github/workflows/release.yml +76 -0
- supamem-0.1.1/.gitignore +9 -0
- supamem-0.1.1/AGENTS.md +116 -0
- supamem-0.1.1/CHANGELOG.md +99 -0
- supamem-0.1.1/CLAUDE.md +43 -0
- supamem-0.1.1/LICENSE +21 -0
- supamem-0.1.1/MIGRATION.md +45 -0
- supamem-0.1.1/PKG-INFO +408 -0
- supamem-0.1.1/README.md +380 -0
- supamem-0.1.1/llms.txt +51 -0
- supamem-0.1.1/pyproject.toml +62 -0
- supamem-0.1.1/src/supamem/__init__.py +2 -0
- supamem-0.1.1/src/supamem/__main__.py +4 -0
- supamem-0.1.1/src/supamem/cli.py +267 -0
- supamem-0.1.1/src/supamem/config.py +168 -0
- supamem-0.1.1/src/supamem/config_io.py +227 -0
- supamem-0.1.1/src/supamem/console.py +116 -0
- supamem-0.1.1/src/supamem/doctor.py +201 -0
- supamem-0.1.1/src/supamem/embedders/__init__.py +33 -0
- supamem-0.1.1/src/supamem/embedders/bm25.py +26 -0
- supamem-0.1.1/src/supamem/embedders/minilm.py +22 -0
- supamem-0.1.1/src/supamem/eval/__init__.py +22 -0
- supamem-0.1.1/src/supamem/eval/auto_goldens.py +70 -0
- supamem-0.1.1/src/supamem/eval/goldens/__init__.py +0 -0
- supamem-0.1.1/src/supamem/eval/goldens/phase_80_1_tuned_hybrid.jsonl +33 -0
- supamem-0.1.1/src/supamem/eval/runner.py +159 -0
- supamem-0.1.1/src/supamem/hooks/__init__.py +31 -0
- supamem-0.1.1/src/supamem/hooks/claude_code.py +217 -0
- supamem-0.1.1/src/supamem/hooks/cursor.py +194 -0
- supamem-0.1.1/src/supamem/hooks/opencode.py +30 -0
- supamem-0.1.1/src/supamem/indexer/__init__.py +179 -0
- supamem-0.1.1/src/supamem/indexer/chunker.py +69 -0
- supamem-0.1.1/src/supamem/indexer/manifest.py +56 -0
- supamem-0.1.1/src/supamem/init.py +214 -0
- supamem-0.1.1/src/supamem/install/__init__.py +98 -0
- supamem-0.1.1/src/supamem/install/_types.py +13 -0
- supamem-0.1.1/src/supamem/install/claude_code.py +211 -0
- supamem-0.1.1/src/supamem/install/cursor.py +178 -0
- supamem-0.1.1/src/supamem/install/opencode.py +136 -0
- supamem-0.1.1/src/supamem/install/share.py +74 -0
- supamem-0.1.1/src/supamem/mcp_server.py +259 -0
- supamem-0.1.1/src/supamem/migrate.py +214 -0
- supamem-0.1.1/src/supamem/retrieval/__init__.py +22 -0
- supamem-0.1.1/src/supamem/retrieval/bm25.py +21 -0
- supamem-0.1.1/src/supamem/retrieval/dense.py +37 -0
- supamem-0.1.1/src/supamem/retrieval/tuned_hybrid.py +203 -0
- supamem-0.1.1/src/supamem/retrieval/types.py +20 -0
- supamem-0.1.1/src/supamem/share/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/commands/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/commands/sm-search.md +33 -0
- supamem-0.1.1/src/supamem/share/cursor-rules/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/cursor-rules/dual-memory.mdc +33 -0
- supamem-0.1.1/src/supamem/share/hooks/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/hooks/qdrant-semantic-guard.sh +36 -0
- supamem-0.1.1/src/supamem/share/rules/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/rules/dual-memory.md +49 -0
- supamem-0.1.1/src/supamem/share/skills/__init__.py +0 -0
- supamem-0.1.1/src/supamem/share/skills/supamem/SKILL.md +41 -0
- supamem-0.1.1/src/supamem/share/skills/supamem/__init__.py +0 -0
- supamem-0.1.1/src/supamem/stats/__init__.py +99 -0
- supamem-0.1.1/src/supamem/stats/counter.py +138 -0
- supamem-0.1.1/src/supamem/update_check.py +249 -0
- supamem-0.1.1/tests/__init__.py +0 -0
- supamem-0.1.1/tests/test_chunker.py +68 -0
- supamem-0.1.1/tests/test_cli_smoke.py +80 -0
- supamem-0.1.1/tests/test_config_discovery.py +125 -0
- supamem-0.1.1/tests/test_config_io.py +147 -0
- supamem-0.1.1/tests/test_console.py +107 -0
- supamem-0.1.1/tests/test_counter.py +121 -0
- supamem-0.1.1/tests/test_doctor.py +111 -0
- supamem-0.1.1/tests/test_eval_runner.py +136 -0
- supamem-0.1.1/tests/test_hook_claude_code.py +174 -0
- supamem-0.1.1/tests/test_hook_cursor.py +157 -0
- supamem-0.1.1/tests/test_indexer.py +189 -0
- supamem-0.1.1/tests/test_init.py +93 -0
- supamem-0.1.1/tests/test_install_claude_code.py +109 -0
- supamem-0.1.1/tests/test_install_cursor.py +98 -0
- supamem-0.1.1/tests/test_install_opencode.py +77 -0
- supamem-0.1.1/tests/test_mcp_server.py +184 -0
- supamem-0.1.1/tests/test_migrate.py +145 -0
- supamem-0.1.1/tests/test_tuned_hybrid.py +141 -0
- 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
|
supamem-0.1.1/.gitignore
ADDED
supamem-0.1.1/AGENTS.md
ADDED
|
@@ -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).
|
supamem-0.1.1/CLAUDE.md
ADDED
|
@@ -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.
|