hl-mem 0.21.0__tar.gz

hl_mem-0.21.0/.env.example

@@ -0,0 +1,4 @@
+LLM_API_KEY=
+EMBEDDING_API_KEY=
+RERANKER_API_KEY=
+IMAGE_API_KEY=

hl_mem-0.21.0/.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

hl_mem-0.21.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] CI/Tooling
+
+## Contract checklist
+
+- [ ] REST API changed? → update `docs/api-schema.json` snapshot
+- [ ] MCP tools changed? → update `docs/mcp-tools.json` snapshot
+- [ ] Config env vars changed? → update `.env.example` + compatibility policy
+- [ ] SQLite schema changed? → new migration + snapshot upgrade test
+- [ ] Breaking change? → deprecation notice in CHANGELOG
+
+## Test plan
+
+- [ ] `python scripts/check_docs_consistency.py` passes
+- [ ] `python scripts/check_imports.py` passes
+- [ ] `ruff check src/` passes
+- [ ] Existing tests not broken

hl_mem-0.21.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Validate tag matches project version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          expected_tag = f"v{project['version']}"
+          actual_tag = os.environ["RELEASE_TAG"]
+          if actual_tag != expected_tag:
+              raise SystemExit(f"release tag {actual_tag!r} does not match project version {expected_tag!r}")
+          PY
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distributions
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hl-mem
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      # 首次创建 PyPI 项目前，需在账户 Publishing 页面添加 pending publisher；项目存在后可在设置中维护。
+      # 需绑定 GitHub publisher（owner lohr13、repository hl_mem、workflow publish.yml、environment pypi）。
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

hl_mem-0.21.0/.github/workflows/quality-smoke.yml

@@ -0,0 +1,22 @@
+name: Quality Smoke
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 2 * * *"
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - run: uv run --frozen python scripts/run_quality_smoke.py
+      - uses: actions/upload-artifact@v7 # Node 24
+        with:
+          name: quality-smoke-${{ github.sha }}
+          path: evaluation/results/

hl_mem-0.21.0/.github/workflows/test.yml

@@ -0,0 +1,165 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Run full test suite
+        env:
+          HL_MEM_ENV: test
+        run: |
+          uv run --frozen python -m pytest tests/ -q --tb=short --cov=hl_mem --cov-report=term-missing --cov-fail-under=60
+      - name: Run migration upgrade test
+        run: uv run --frozen python -m pytest tests/test_migration_upgrade.py -q --tb=short
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - run: uv run --frozen ruff check .
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - run: uv run --frozen python -m mypy src/hl_mem/ --ignore-missing-imports
+
+  quality-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - run: uv run --frozen python scripts/run_quality_smoke.py
+
+  recall-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Run offline recall contract and fixture gate
+        if: ${{ hashFiles('tests/eval/datasets/recall_v2.jsonl') != '' && hashFiles('tests/eval/datasets/recall_v2.manifest.json') != '' && hashFiles('tests/eval/baselines/baseline_v019_ci.json') != '' }}
+        run: uv run --frozen python -m tests.eval.ci_gate
+      - name: Report unavailable private recall fixtures
+        if: ${{ hashFiles('tests/eval/datasets/recall_v2.jsonl') == '' || hashFiles('tests/eval/datasets/recall_v2.manifest.json') == '' || hashFiles('tests/eval/baselines/baseline_v019_ci.json') == '' }}
+        run: echo "Recall fixture gate skipped because private evaluation artifacts are not checked into Git."
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Check formatting
+        run: |
+          uv run --frozen black --check .
+          uv run --frozen isort --check-only .
+
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Build wheel and source distribution
+        run: uv run --frozen python -m build
+      - name: Verify import in a clean environment
+        run: |
+          python -m venv .build-venv
+          .build-venv/bin/python -m pip install --upgrade pip
+          .build-venv/bin/python -m pip install dist/*.whl
+          .build-venv/bin/python -c "import hl_mem; print(hl_mem.__version__)"
+
+  migrations:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Apply migrations from an empty database
+        run: |
+          uv run --frozen python -c "import tempfile; from pathlib import Path; from hl_mem.storage.database import Database; path = Path(tempfile.mkdtemp()) / 'fresh.db'; db = Database(path); connection = db.open(); applied = {row[0] for row in connection.execute('SELECT version FROM schema_migrations')}; expected = {path.stem for path in Path('src/hl_mem/storage/migrations').glob('*.sql')}; missing = expected - applied; assert not missing, f'missing SQL migrations: {sorted(missing)}'; db.close(); print(f'applied {len(expected)} SQL migrations')"
+
+  import-boundary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Check dependency direction
+        run: uv run --frozen python scripts/check_imports.py
+
+  doc-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: python scripts/check_docs_consistency.py
+
+  contract-snapshots:
+    # NOTE: Snapshot mismatch means contract changed.
+    # Reviewers must verify this is intentional before approving.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2, Node 24
+      - run: uv sync --frozen
+      - name: Check OpenAPI and MCP contracts
+        run: |
+          uv run --frozen python scripts/check_openapi_snapshot.py
+          uv run --frozen python scripts/check_mcp_snapshot.py

hl_mem-0.21.0/.gitignore

@@ -0,0 +1,58 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.db
+*.egg-info/
+dist/
+build/
+.venv/
+hl_mem_test.db
+hl_mem_budget_test.json
+.env
+.env.bak*
+hl_mem.toml
+*.db
+*.db-*
+*.budget.json
+var/*.db
+var/*.db-*
+var/*.db.cleanup_backup_*
+var/*.db.bak_*
+var/*.db.bak.*
+var/*.db.manifest.json
+var/*.log
+*.log
+pytest_*.txt
+pending_commits.txt
+tests/eval/reports/*.json
+evaluation/results/
+scripts/*.stdout.log
+scripts/*.stderr.log
+scripts/*.pid
+scripts/*.lock
+scripts/*artifacts.txt
+scripts/*.partial.jsonl
+scripts/benchmark_runs/
+scripts/extraction_benchmark_results*.jsonl
+scripts/extraction_benchmark_results*.manifest.json
+scripts/extraction_benchmark_results*.gold_eval.txt
+scripts/extraction_benchmark_results*.analysis.md
+scripts/extraction_benchmark_glm*.jsonl
+scripts/glm52_*.jsonl
+fix_env_ak.py
+test_hermes_ak.py
+
+# 评测数据和报告（包含敏感信息，不推送到公开仓库）
+tests/eval/datasets/
+tests/eval/baselines/
+docs/eval-reports/
+
+# cc-connect runtime artifacts (not part of this repo)
+.cc-connect/
+
+
+# hlmem watchdog runtime state
+var/watchdog.state
+var/crash-packages/
+

hl_mem-0.21.0/AGENTS.md

@@ -0,0 +1,155 @@
+# HL-Mem 项目 AGENTS.md
+
+## 项目概述
+
+HL-Mem 是面向 AI Agent 的本地优先记忆系统。核心设计：事件溯源双通道 + 双时间模型 + 证据链 + slot+tags 分类体系 + importance 联动 TTL + 多因子召回 + 完整生命周期管理。
+
+**当前版本：v0.20.2（2026-08-02）**
+
+## 技术栈
+
+- **运行时**：Python 3.11+，FastAPI + uvicorn
+- **存储**：SQLite WAL + FTS5（全文检索）+ 向量 BLOB（暴力余弦，首版）
+- **LLM 提取**：API 密钥通过 .env 配置，provider/model 通过 TOML 配置，使用结构化 JSON 输出
+- **Embedding**：API 密钥通过 .env 配置，provider/model/维度通过 TOML 配置
+- **Reranker**：API 密钥通过 .env 配置，provider/model 通过 TOML 配置
+- **分类体系**：SLOT_REGISTRY（15 operational slot + 40 topic tags；Phase 18 已接入检索，soft boost 默认开启，独立 tag channel 默认关闭待评测）
+- **TTL**：retention 纯函数（scope × importance 三档）
+- **跨 subject 去重**：DedupJudge（audit-only 默认开启）
+- **包管理**：uv（lockfile: uv.lock）
+- **测试**：pytest + pytest-asyncio（asyncio_mode=auto）730 passed，1 skipped
+
+## 代码结构
+
+```
+src/hl_mem/
+├── api/                    # FastAPI 适配层
+│   ├── server.py              # REST API (16 routes)
+│   └── schemas.py             # Pydantic DTO
+├── application/            # 共享应用服务
+│   ├── ingest.py              # IngestService
+│   ├── recall.py              # RecallService
+│   └── forget.py              # ForgetService
+├── domain/                 # 纯领域逻辑（不依赖基础设施）
+│   ├── claims/                # claim 写入/冲突/去重/retention/query_tags
+│   ├── temporal.py            # 双时间可见性
+│   ├── relations.py           # 记忆关系
+│   ├── entity.py              # 实体归一化
+│   ├── recall.py              # 召回领域逻辑
+│   └── content.py             # 多模态内容协议
+├── core/                   # 纯数学
+│   └── vector.py              # cosine similarity
+├── ingest/                 # 数据摄入
+│   ├── llm_extractor.py       # LLM 提取器
+│   ├── extractors.py          # FakeExtractor / LLMExtractor
+│   ├── chunking.py            # 结构感知分块
+│   ├── embedder.py            # Embedding 向量化
+│   ├── event_filter.py        # 事件预过滤
+│   └── budget.py              # Token 预算控制
+├── llm/                    # LLM 客户端（Provider 解耦）
+│   ├── client.py              # LLMClient
+│   ├── providers.py           # 百炼/智谱/OpenAI-compatible
+│   └── types.py               # LLMRequest/LLMResponse
+├── recall/                 # 召回层
+│   ├── staged_pipeline.py     # 三通道 RRF (FTS + Dense + Tag)
+│   ├── trace.py               # SearchTrace 可观测性
+│   ├── ranking.py             # 多因子排序
+│   ├── reranker.py            # Reranker 重排
+│   ├── relation_expansion.py  # 一跳关系扩展
+│   └── observation.py         # 派生记忆构建
+├── storage/                # 存储层（按职责拆分）
+│   ├── database.py            # SQLite WAL + migration runner
+│   ├── claims.py              # ClaimRepository
+│   ├── events.py              # EventRepository
+│   ├── evidence.py            # EvidenceRepository
+│   ├── experience.py          # ExperienceRepository
+│   ├── jobs.py                # JobRepository
+│   ├── relation_proposals.py  # 关系候选审计
+│   ├── usefulness.py          # 反馈效用聚合
+│   ├── backup.py              # 在线备份
+│   └── migrations/            # 36 SQL migrations (001-036)
+├── workers/                # 后台任务
+│   ├── worker.py              # Job 调度器
+│   ├── ttl.py                 # TTL 过期
+│   ├── decay.py               # 置信度衰减
+│   ├── consolidate.py         # LLM 语义归并
+│   ├── deduplicate.py         # 跨 subject 语义去重
+│   ├── backfill_expires_at.py # TTL 回填工具
+│   ├── discover_relations.py  # 关系候选发现
+│   ├── mental_models.py       # Mental Model 维护
+│   ├── rebuild_usefulness.py  # usefulness 重建
+│   └── induce_policies.py     # 策略归纳
+├── experience/             # Experience 通道
+│   └── service.py             # Episode/Trace/Policy
+├── evaluation/             # Benchmark / LongMemEval
+├── observability/          # 审计日志与 LLM spans
+├── security/               # retention 策略
+├── adapters/hermes/        # Hermes 集成
+│   ├── provider.py            # HermesMemoryProvider
+│   └── plugin/                # 薄委托层
+├── mcp/
+│   └── server.py              # MCP 工具契约
+├── components.py           # 统一组件工厂
+├── settings.py             # Settings dataclass + 校验
+├── protocols.py            # 接口协议
+├── errors.py               # 异常族
+├── http_utils.py           # 统一重试工具
+├── lifecycle.py            # 状态机守卫
+└── cli.py                  # CLI 入口
+```
+
+## 测试
+
+```bash
+.venv/Scripts/python.exe -m pytest tests/unit/ -q --tb=short
+```
+
+当前：730 passed，1 skipped。
+
+## 关键设计决策
+
+### 写入管线
+- fact_hash v2（JSON 数组有边界哈希）→ conflict_key（canonical attribute slot）→ semantic dedup（cosine > 0.82, best-match）
+- 冲突判定：确定性规则优先（ConflictResolver），灰区走 LLM 四分类（ConflictConsolidator）
+- **事务原子化**：整个写入流程（update_status + insert_claim + supersede + evidence_link）在单一 BEGIN IMMEDIATE 中
+
+### 召回管线
+- FTS5 全文检索 + dense vector 余弦相似度 → RRF 融合
+- 多因子排序：recency / importance / access_count / scope / helpful_rate
+- 可选 Reranker（密钥与 provider/model 由配置提供）
+- 双时间过滤：valid_from/valid_to + recorded_from/recorded_to
+- **上下文预算**：token_budget + context_mode="packed" + 跨类型配额
+- 偏好专用召回 intent（RecallIntent.PREFERENCE）
+- **派生记忆接入**：recall 自动查询活跃 derivation 并填充 observations
+
+### 生命周期管理
+- TTL 过期（ephemeral）→ 线性衰减（temporal/permanent 分级）→ 归档（embedding 清空）→ 重分类
+- 访问频率延缓衰减（每 10 次召回 +30 天）
+- **冲突终态收敛**：conflict_cases 状态机（pending → auto_resolved/manual_required → resolved/rejected）
+- stale 传播：claim 撤回时关联的 derivation 自动标记 stale
+
+### 架构分层
+- **api/** 是适配层（FastAPI DTO + 路由），不含业务逻辑
+- **application/** 是应用服务层，拥有事务边界
+- **domain/** + **core/** 是纯函数，不依赖基础设施
+- **storage/** 是数据访问层，只依赖 domain 和 core
+- **workers/** 是后台调度，通过 application 服务操作数据
+- **lifecycle.py** 是状态机守卫，所有状态变更统一经过 assert_transition()
+
+## 配置
+
+环境变量（关键项）：
+- `HL_MEM_ENV` — dev/production
+- `HL_MEM_DB_PATH` — SQLite 路径
+- `HL_MEM_EMBEDDER` — fake/real
+- `HL_MEM_RERANKER` — off/fake/on/real
+- `LLM_API_KEY` — 百炼 Coding AK
+- `EMBEDDING_API_KEY` — 百炼通用 AK
+- `HL_MEM_DECAY_TEMPORAL_DAYS` / `HL_MEM_DECAY_PERMANENT_DAYS` — 衰减策略
+- `HL_MEM_DEDUP_THRESHOLD` — 语义去重阈值
+
+集中配置：`config.py`（常量）+ `settings.py`（Settings 校验）+ `components.py`（工厂）
+
+## Migration
+
+36 个 SQL migration（001-036），按版本号顺序执行。不可变。

hl_mem-0.21.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to HL-Mem
+
+感谢你帮助改进 HL-Mem。提交应聚焦单一问题，并保持本地优先、证据可追溯和向后兼容的设计原则。
+
+## Development setup
+
+需要 Python 3.11+、Git 和 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+git clone git@github.com:lohr13/hl_mem.git
+cd hl_mem
+uv sync --extra dev
+cp .env.example .env
+```
+
+默认测试使用 fake providers，不需要外部 API key。仅在运行真实 Provider 检查时配置 `.env`，不要提交凭据、数据库或生成的报告。
+
+## Tests and checks
+
+提交前运行与改动范围匹配的检查；行为变更应包含回归测试。
+
+```bash
+# Full suite
+.venv/Scripts/python.exe -m pytest tests/ -q --tb=short
+
+# Unit tests
+.venv/Scripts/python.exe -m pytest tests/unit/ -q --tb=short
+
+# Formatting and import order
+uv run black --check --line-length 120 src tests
+uv run isort --check-only --profile black src tests
+
+# Architecture import boundaries
+uv run python scripts/check_imports.py
+```
+
+## Code style
+
+- 使用 Python 3.11+ 和完整的 PEP 484 类型标注。
+- Black 行宽为 120；isort 使用 `profile=black`。
+- 模块、类和公开函数使用中文 docstring；复杂逻辑使用简洁中文注释。
+- `domain/` 与 `core/` 保持纯净，不反向依赖 `storage/`、`api/` 或 `workers/`。
+- 运行时模型、端口、路径、超时和密钥必须来自设置、配置文件或环境变量。
+- 外部 API 必须设置超时和 retry，并提供可操作的错误信息。
+- 已发布 migration 不可修改；schema 变化应新增顺序 migration。
+
+## Pull requests
+
+1. 从最新 `main` 创建短生命周期分支。
+2. 一个 PR 只解决一个问题；避免无关重构和格式噪声。
+3. 更新相关文档、CHANGELOG 和能力矩阵，并添加或更新测试。
+4. 在 PR 描述中说明动机、实现方式、风险、验证命令和结果。
+5. 确认没有提交密钥、运行数据库、缓存或 `var/` 数据。
+6. 响应评审意见；涉及行为变化时补充可复现证据。
+
+提交信息使用英文 Conventional Commits，例如：
+
+```text
+feat(recall): add bounded query expansion
+fix(storage): preserve temporal visibility
+docs: clarify provider configuration
+```