turbo-quant-memory 0.28.0__tar.gz

turbo_quant_memory-0.28.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Ruff
+        run: uv run --no-sync ruff check src tests
+      - name: Mypy
+        run: uv run --no-sync mypy src/turbo_memory_mcp
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.11"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    env:
+      FASTEMBED_CACHE_PATH: ${{ github.workspace }}/.fastembed-cache
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Cache fastembed model
+        uses: actions/cache@v6
+        with:
+          path: .fastembed-cache
+          key: fastembed-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            fastembed-${{ runner.os }}-
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Run tests
+        run: uv run --no-sync pytest -q

turbo_quant_memory-0.28.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: publish
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token stored anywhere.
+# One-time setup on PyPI: Account -> Publishing -> add a pending publisher with
+#   project: turbo-memory-mcp | owner: Lexus2016 | repo: turbo_quant_memory
+#   workflow: publish.yml     | environment: pypi
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check metadata renders on PyPI
+        run: uvx twine check dist/*
+      - name: Fail if the tag and the package version disagree
+        if: github.event_name == 'release'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv run --no-project python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          test "$tag" = "$pkg" || { echo "tag $tag != pyproject $pkg"; exit 1; }
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

turbo_quant_memory-0.28.0/.gitignore

@@ -0,0 +1,16 @@
+.serena/
+.omc/
+.pytest_cache/
+.venv/
+.gemini/
+.claude/
+__pycache__/
+*.py[cod]
+.fastembed-cache/
+
+# Generated retrieval-quality reports embed real per-project data — keep local only
+benchmarks/retrieval_quality.json
+benchmarks/retrieval_quality.md
+benchmarks/retrieval_quality_global.json
+benchmarks/retrieval_quality_global.md
+benchmarks/paraphrase_fixture.json

turbo_quant_memory-0.28.0/.planning/PROJECT.md

@@ -0,0 +1,100 @@
+# Turbo Quant Memory for AI Agents
+
+## What This Is
+
+Turbo Quant Memory for AI Agents is a local-first MCP server for AI coding agents that stores large Markdown knowledge bases outside the active chat context and returns compressed, task-relevant context on demand. It is inspired by TurboQuant's compression mindset, but it operates at the memory and retrieval layer rather than modifying model internals or KV cache behavior.
+
+Turbo Quant Memory for AI Agents є local-first MCP-сервером для AI coding-агентів, який зберігає великі Markdown-бази знань поза активним контекстом чату і повертає стислий, релевантний до завдання контекст за запитом. Він натхненний підходом TurboQuant до стиснення, але працює на рівні пам'яті та retrieval, а не змінює внутрішню KV-cache логіку моделі.
+
+## Core Value
+
+Agents can offload cold project context and recover only the minimum high-signal context needed to act correctly.
+
+Агенти можуть виносити "холодний" контекст проєкту з активного діалогу і повертати лише мінімальний високосигнальний контекст, потрібний для правильної роботи.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] AI agents such as Claude Code, Codex, Cursor, OpenCode, and Antigravity can connect to the same memory server through MCP.
+- [ ] AI-агенти на кшталт Claude Code, Codex, Cursor, OpenCode та Antigravity можуть підключатися до одного й того самого memory server через MCP.
+- [ ] Retrieval defaults to compressed context cards, with full hydration available only when needed.
+- [ ] Retrieval за замовчуванням повертає стислі context cards, а повне hydrate-повернення доступне лише за потреби.
+- [ ] Setup and connection must stay extremely simple: local install, stdio MCP, minimal config, CPU-friendly defaults.
+- [ ] Налаштування і підключення мають залишатися максимально простими: локальна інсталяція, stdio MCP, мінімальний конфіг, CPU-friendly дефолти.
+- [ ] Memory must work both per project and across all projects through clear namespace rules.
+- [ ] Пам'ять має працювати і в межах одного проєкту, і між усіма проєктами через чіткі namespace-правила.
+- [ ] The server must allow agents to write back important learnings and reuse them in later sessions.
+- [ ] Сервер має дозволяти агентам записувати важливі висновки і повторно використовувати їх у наступних сесіях.
+
+### Out of Scope
+
+- Direct modification of Claude or Anthropic model KV cache — this project works at the MCP memory layer only.
+- Пряма модифікація KV cache Claude або моделей Anthropic — цей проєкт працює лише на рівні MCP-пам'яті.
+- Managed multi-tenant cloud platform — MVP stays local-first for fast deployment and low operational overhead.
+- Керована multi-tenant cloud-платформа — MVP залишається local-first для швидкого розгортання і низьких операційних витрат.
+- Mandatory GPU inference stack — CPU-first operation is required for easy adoption.
+- Обов'язковий GPU-стек для інференсу — для легкого старту потрібна робота на CPU.
+
+## Context
+
+- TurboQuant research from Google Research, published on March 24, 2026, shows that aggressive compression plus selective recovery can preserve usefulness while sharply reducing memory costs. The relevant product inference for this project is not "we can change Claude's KV cache", but "we can aggressively compress external context and recover full fidelity only when needed."
+- Дослідження TurboQuant від Google Research, опубліковане 24 березня 2026 року, показує, що агресивне стиснення разом із вибірковим відновленням може зберігати корисність і різко знижувати витрати пам'яті. Важливий продуктовий висновок для цього проєкту не в тому, що "ми можемо змінити KV cache Claude", а в тому, що "ми можемо агресивно стискати зовнішній контекст і повертати повну точність лише за потреби".
+- Official Anthropic Claude Code documentation confirms MCP servers can be connected through `claude mcp add ...` or `.mcp.json`, which supports a simple local stdio deployment model.
+- Офіційна документація Anthropic Claude Code підтверджує, що MCP-сервери можна підключати через `claude mcp add ...` або `.mcp.json`, що підходить для простої локальної stdio-моделі розгортання.
+- Official OpenAI Codex documentation confirms MCP servers can be added via `codex mcp add ...`, and official Cursor and OpenCode docs confirm project-level and user-level MCP configuration. A current Flutter integration guide also documents Antigravity setup for custom MCP servers, which is a strong compatibility signal for the same architecture.
+- Офіційна документація OpenAI Codex підтверджує, що MCP-сервери можна додавати через `codex mcp add ...`, а офіційна документація Cursor і OpenCode підтверджує project-level та user-level конфігурацію MCP. Актуальний Flutter integration guide також документує налаштування Antigravity для кастомних MCP-серверів, що є сильним сигналом сумісності для цієї самої архітектури.
+- Official MCP Python SDK documentation provides a simple Python server path with FastMCP and stdio support, which fits the project's deployment constraint.
+- Офіційна документація MCP Python SDK дає простий шлях до Python-сервера через FastMCP і stdio, що відповідає обмеженню про просте розгортання.
+- LanceDB and Sentence Transformers both support a local embedded workflow suitable for a file-backed, CPU-usable MVP.
+- LanceDB і Sentence Transformers обидва підтримують локальний embedded-режим, придатний для file-backed MVP, який можна використовувати на CPU.
+
+## Constraints
+
+- **Tech stack**: Python 3.11+, MCP Python SDK, embedded local storage, CPU-friendly embeddings — to keep installation and maintenance simple.
+- **Техстек**: Python 3.11+, MCP Python SDK, embedded локальне сховище, CPU-friendly embeddings — щоб інсталяція і підтримка були простими.
+- **Deployment**: Must run locally over stdio and connect to Claude Code without any hosted dependency.
+- **Розгортання**: Має запускатися локально через stdio і підключатися до агент-клієнтів без будь-якої hosted-залежності.
+- **Compatibility**: The same core server should be usable from Claude Code, Codex, Cursor, OpenCode, and Antigravity with client-specific config wrappers only.
+- **Сумісність**: Той самий core-server має використовуватися з Claude Code, Codex, Cursor, OpenCode і Antigravity, а різнитися повинні лише client-specific config wrappers.
+- **Performance**: Retrieval should feel interactive on a laptop-class machine for small and medium knowledge bases.
+- **Продуктивність**: Retrieval має відчуватися інтерактивним на звичайному ноутбуці для малих і середніх баз знань.
+- **Quality**: Compression must preserve source traceability and provide a clear upgrade path to fuller context.
+- **Якість**: Стиснення має зберігати traceability до джерела і давати чіткий шлях до повнішого контексту.
+- **Security**: Access must stay explicit to user-approved directories; no silent network requirement for core memory flow.
+- **Безпека**: Доступ має бути явним лише до user-approved директорій; для базового memory-flow не повинно бути прихованої мережевої залежності.
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Build a memory-layer system, not a model patch | Claude Code uses hosted models, so MCP-side compression is the controllable layer | — Pending |
+| Use Markdown as the source of truth | Easy onboarding, inspectable storage, low lock-in | — Pending |
+| Use an embedded local vector store | Zero separate service and easier deployment | — Pending |
+| Default to compressed recall plus on-demand hydration | Maximizes token savings while reducing quality loss on edge cases | — Pending |
+| Prefer CPU-friendly local embeddings first | Keeps MVP easy to install and run on developer laptops | — Pending |
+| Design namespaces from day one | Project-only memory and cross-project memory must not get mixed accidentally | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `$gsd-transition`):
+1. Requirements invalidated? -> Move to Out of Scope with reason
+2. Requirements validated? -> Move to Validated with phase reference
+3. New requirements emerged? -> Add to Active
+4. Decisions to log? -> Add to Key Decisions
+5. "What This Is" still accurate? -> Update if drifted
+
+**After each milestone** (via `$gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check -> still the right priority?
+3. Audit Out of Scope -> reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-03-25 after initialization*

turbo_quant_memory-0.28.0/.planning/REQUIREMENTS.md

@@ -0,0 +1,135 @@
+# Requirements: Turbo Quant Memory for AI Agents
+
+**Defined:** 2026-03-25
+**Core Value:** Agents can offload cold project context and recover only the minimum high-signal context needed to act correctly.
+
+## v1 Requirements
+
+### Integration
+
+- [x] **INT-01**: User can run the memory server locally over stdio so Claude Code can connect to it as an MCP server. / Користувач може запустити memory server локально через stdio, щоб Claude Code підключався до нього як до MCP-сервера.
+- [x] **INT-02**: User can install and run the MVP without a separate database service or mandatory GPU dependency. / Користувач може встановити і запустити MVP без окремого database-сервісу та без обов'язкової GPU-залежності.
+- [x] **INT-03**: User can connect the server to Claude Code using a documented `claude mcp add ...` or `.mcp.json` flow. / Користувач може підключити сервер до Claude Code через задокументований сценарій `claude mcp add ...` або `.mcp.json`.
+- [x] **INT-04**: User has documented MCP connection examples for Claude Code, Codex, Cursor, OpenCode, and Antigravity. / Користувач має задокументовані приклади MCP-підключення для Claude Code, Codex, Cursor, OpenCode і Antigravity.
+
+### Scope
+
+- [x] **SCP-01**: User can store and query project-scoped memory tied to the current repository. / Користувач може зберігати і запитувати project-scoped memory, прив'язану до поточного репозиторію.
+- [x] **SCP-02**: User can store and query global memory shared across all projects on the same machine. / Користувач може зберігати і запитувати global memory, спільну для всіх проєктів на одній машині.
+- [x] **SCP-03**: Agent can search in `project`, `global`, or `hybrid` mode with deterministic precedence rules. / Агент може шукати в режимах `project`, `global` або `hybrid` з детермінованими правилами пріоритету.
+- [x] **SCP-04**: Every returned result identifies its scope and project origin to prevent accidental cross-project contamination. / Кожен повернений результат ідентифікує свій scope і project origin, щоб запобігти випадковому змішуванню проєктів.
+
+### Ingestion
+
+- [x] **ING-01**: User can register one or more Markdown directories for indexing. / Користувач може зареєструвати одну або кілька Markdown-директорій для індексації.
+- [x] **ING-02**: Server splits Markdown into stable retrievable blocks using heading-aware chunking with fallback size limits. / Сервер ділить Markdown на стабільні retrievable-блоки через heading-aware chunking із fallback size limits.
+- [x] **ING-03**: User can reindex only changed content instead of rebuilding the entire memory store every time. / Користувач може переіндексувати лише змінений контент, а не перебудовувати весь memory store щоразу.
+
+### Retrieval
+
+- [x] **RET-01**: Agent can run semantic search and receive the top relevant blocks with score, source path, and block ID. / Агент може виконати semantic search і отримати top-relevant блоки зі score, source path і block ID.
+- [x] **RET-02**: Agent can request a compressed context card for a block that removes low-signal noise while preserving the key meaning. / Агент може запросити compressed context card для блока, яка прибирає low-signal шум і зберігає ключовий зміст.
+- [x] **RET-03**: Agent can hydrate a fuller block or source excerpt on demand when the compressed result is insufficient. / Агент може за потреби hydrate-нути повніший блок або source excerpt, коли стислого результату недостатньо.
+- [x] **RET-04**: Agent can request related blocks around a result to recover local neighbourhood context. / Агент може запитати related blocks навколо результату, щоб відновити локальний neighbourhood context.
+
+### Memory
+
+- [x] **MEM-01**: Agent can write back an important decision, lesson, or reusable note into persistent memory. / Агент може записати назад у persistent memory важливе рішення, урок або reusable note.
+- [x] **MEM-02**: Stored memory notes are indexed and searchable together with Markdown source content. / Збережені memory notes індексуються і шукаються разом із вихідним Markdown-контентом.
+
+### Safety
+
+- [x] **SAFE-01**: Every returned result includes source provenance that lets the agent or user trace it back to the original file and block. / Кожен повернений результат містить provenance до джерела, щоб агент або користувач могли відстежити його до оригінального файла і блока.
+- [x] **SAFE-02**: The server avoids returning full raw files by default and instead requires explicit hydration calls for larger context. / Сервер не повертає повні сирі файли за замовчуванням і вимагає явного hydration-виклику для більшого контексту.
+
+### Operations
+
+- [x] **OPS-01**: User can inspect basic health, index freshness, and store statistics from the server. / Користувач може переглядати базовий health, freshness індексу і статистику store безпосередньо із сервера.
+- [x] **OPS-02**: User has a documented smoke test that proves install, indexing, search, and hydration work end-to-end. / Користувач має задокументований smoke test, який підтверджує, що install, indexing, search і hydration працюють end-to-end.
+
+## v2 Requirements
+
+### Compression Intelligence
+
+- **CMP-01**: Agent can request multi-level summaries from one source block (brief, standard, deep). / Агент може запитувати multi-level summaries для одного source-блока (brief, standard, deep).
+- **CMP-02**: Server can use an optional local summarizer such as Ollama for higher-quality compression. / Сервер може використовувати optional local summarizer на кшталт Ollama для кращого стиснення.
+
+### Retrieval Quality
+
+- **QLT-01**: Server can apply reranking to improve precision on ambiguous searches. / Сервер може застосовувати reranking для кращої precision на неоднозначних запитах.
+- **QLT-02**: Server can benchmark token savings versus quality loss on a curated task suite. / Сервер може benchmark-нути економію токенів проти втрати якості на curated task suite.
+
+### Collaboration
+
+- **COL-01**: Multiple named memory spaces can coexist for separate projects or teams. / Кілька іменованих memory spaces можуть співіснувати для різних проєктів або команд.
+- **COL-02**: Notes can carry richer relationship metadata beyond tags. / Нотатки можуть нести багатші relationship metadata, ніж прості теги.
+
+### Knowledge Base Lifecycle
+
+- **KBL-01**: Server exposes `lint_knowledge_base(...)` to run structural diagnostics over Markdown knowledge bases. / Сервер надає `lint_knowledge_base(...)` для структурної діагностики Markdown knowledge base.
+- **KBL-02**: Lint results report broken internal links, orphan candidates, and duplicate normalized titles. / Результати lint показують биті internal links, orphan candidates і дублікати нормалізованих заголовків.
+- **KBL-03**: Lint supports both explicit root paths and previously registered Markdown roots. / Lint підтримує і явні root paths, і раніше зареєстровані Markdown roots.
+
+### Secrets Vault
+
+- **VLT-01**: Server stores per-project secrets encrypted at rest under `~/.turbo-quant-memory/projects/<project_id>/secrets/vault.tqv` using AES-256-GCM with a per-project master key. / Сервер зберігає per-project секрети зашифрованими at-rest у `~/.turbo-quant-memory/projects/<project_id>/secrets/vault.tqv` через AES-256-GCM з per-project майстер-ключем.
+- **VLT-02**: Master key resolution survives daemon restarts and machine reboots via OS keyring (Keychain on macOS, libsecret on Linux, Credential Manager on Windows) with an `TQMEMORY_SECRETS_PASSPHRASE` env-var fallback; no interactive prompt is used as fallback. / Розв'язання майстер-ключа переживає перезапуски daemon'а та reboot машини через OS keyring (Keychain на macOS, libsecret на Linux, Credential Manager на Windows) із fallback на env var `TQMEMORY_SECRETS_PASSPHRASE`; інтерактивний prompt як fallback не використовується.
+- **VLT-03**: Server exposes `set_secret`, `get_secret`, `list_secrets`, and `delete_secret` MCP tools scoped implicitly to the active project. / Сервер надає MCP-інструменти `set_secret`, `get_secret`, `list_secrets`, `delete_secret`, неявно прив'язані до активного проєкту.
+- **VLT-04**: Secret values are NEVER returned via `semantic_search`, `hydrate`, or `lint_knowledge_base`; the indexer refuses to traverse any `secrets/` subdirectory. / Значення секретів НІКОЛИ не повертаються через `semantic_search`, `hydrate` або `lint_knowledge_base`; індексатор відмовляється обходити будь-яку підпапку `secrets/`.
+- **VLT-05**: Every secret access (`set`, `get`, `list`, `delete`) is recorded in `~/.turbo-quant-memory/audit/secrets.jsonl` by `(timestamp, project_id, action, name)` only; values are never logged. / Кожен доступ до секрету (`set`, `get`, `list`, `delete`) записується в `~/.turbo-quant-memory/audit/secrets.jsonl` тільки за `(timestamp, project_id, action, name)`; значення не логуються.
+- **VLT-06**: On upgrade, the migration runner enumerates existing project directories under `~/.turbo-quant-memory/projects/*` and provisions an empty per-project vault and metadata file immediately, not lazily. / При оновленні migration runner проходить існуючі project-каталоги у `~/.turbo-quant-memory/projects/*` і одразу створює порожній per-project vault і metadata-файл, а не лінько при першому використанні.
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Direct Anthropic or Claude KV-cache quantization / Пряма квантизація KV-cache Anthropic або Claude | Not available at the MCP integration layer / Це недоступно на рівні MCP-інтеграції |
+| Hosted SaaS control plane / Hosted SaaS control plane | Opposes the easy local deployment goal / Суперечить цілі простого локального розгортання |
+| Mandatory GPU-only inference path / Обов'язковий GPU-only шлях інференсу | Too much setup friction for MVP / Для MVP це створює зайве тертя під час запуску |
+| Rich web admin UI / Багатий web admin UI | Not required before the core memory loop proves value / Не потрібен, поки не доведена цінність базового memory loop |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| INT-01 | Phase 1 | Complete |
+| INT-02 | Phase 1 | Complete |
+| INT-03 | Phase 1 | Complete |
+| INT-04 | Phase 1 | Complete |
+| SCP-01 | Phase 2 | Complete |
+| SCP-02 | Phase 2 | Complete |
+| SCP-03 | Phase 2 | Complete |
+| SCP-04 | Phase 2 | Complete |
+| ING-01 | Phase 3 | Complete |
+| ING-02 | Phase 3 | Complete |
+| ING-03 | Phase 3 | Complete |
+| RET-01 | Phase 4 | Complete |
+| RET-02 | Phase 4 | Complete |
+| SAFE-01 | Phase 4 | Complete |
+| SAFE-02 | Phase 4 | Complete |
+| RET-03 | Phase 5 | Complete |
+| RET-04 | Phase 5 | Complete |
+| MEM-01 | Phase 5 | Complete |
+| MEM-02 | Phase 5 | Complete |
+| OPS-01 | Phase 6 | Complete |
+| OPS-02 | Phase 6 | Complete |
+| KBL-01 | Phase 7 | Complete |
+| KBL-02 | Phase 7 | Complete |
+| KBL-03 | Phase 7 | Complete |
+| VLT-01 | Phase 9 | Complete |
+| VLT-02 | Phase 9 | Complete |
+| VLT-03 | Phase 9 | Complete |
+| VLT-04 | Phase 9 | Complete |
+| VLT-05 | Phase 9 | Complete |
+| VLT-06 | Phase 9 | Complete |
+
+**Coverage:**
+- v1 requirements: 21 total
+- v2 KBL requirements: 3 total (shipped via Phase 7 quick extension)
+- v2 VLT requirements: 6 total (Phase 9, planned 2026-05-25)
+- Mapped to phases: 30
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-03-25*
+*Last updated: 2026-05-25 with VLT-01..VLT-06 for Phase 9 secrets vault*

turbo_quant_memory-0.28.0/.planning/ROADMAP.md

@@ -0,0 +1,183 @@
+# Roadmap: Turbo Quant Memory for AI Agents
+
+**Defined:** 2026-03-25
+**Requirements mapped:** 30 / 30 (21 v1 + 3 KBL + 6 VLT)
+**Status:** v1 core shipped; post-v1 hardening and rollout slices shipped through `v0.3.0`; Phase 9 secrets vault planned for v0.7.0
+
+## Overview
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | Client Integration Foundation | Start a local stdio MCP server that multiple agent clients can connect to with a minimal install path | INT-01, INT-02, INT-03, INT-04 | 4 |
+| 2 | Namespace Model | Define and implement project and global memory scopes with safe precedence rules | SCP-01, SCP-02, SCP-03, SCP-04 | 4 |
+| 3 | Markdown Ingestion | Build deterministic Markdown chunking and incremental indexing into local memory storage | ING-01, ING-02, ING-03 | 4 |
+| 4 | Compressed Retrieval | Return compact, provenance-rich retrieval results instead of raw file dumps | RET-01, RET-02, SAFE-01, SAFE-02 | 4 |
+| 5 | Hydration and Write-Back | Add fuller-context recovery and persistent session memory | RET-03, RET-04, MEM-01, MEM-02 | 4 |
+| 6 | Hardening and Adoption | Add observability, smoke tests, and easy operator guidance for real use | OPS-01, OPS-02 | 4 |
+| 7 | Knowledge-Base Hygiene (Quick Extension) | Add structural wiki linting so agent-managed markdown corpora stay consistent over time | KBL-01, KBL-02, KBL-03 | 3 |
+| 8 | Memory Resilience, Migration Stats, Release Rollout, and Client Refresh | Make derived indexes self-healing across upgrades, prove token savings with persistent telemetry, and refresh the live client rollout contract | OPS-01, OPS-02 | 4 |
+| 9 | Project-Scoped Encrypted Secrets Vault | Add per-project encrypted secrets storage so AI agents can persist and retrieve credentials across sessions without leaking them into the embedding/FTS index or backups | VLT-01, VLT-02, VLT-03, VLT-04, VLT-05, VLT-06 | 4 |
+
+## Phase Details
+
+### Phase 1: Client Integration Foundation
+
+**Goal:** Establish the smallest useful server that can run locally, expose initial tools, and be connected to supported agent clients without custom infrastructure.
+
+**Status:** Complete (2026-03-25)
+
+**Requirements:** `INT-01`, `INT-02`, `INT-03`, `INT-04`
+
+**UI hint:** no
+
+**Success criteria:**
+1. A developer can install dependencies and launch the server locally over stdio.
+2. Claude Code can connect to the server using a documented `claude mcp add ...` or `.mcp.json` configuration.
+3. The server exposes a minimal, discoverable MCP tool surface for future memory operations.
+4. Documented setup examples exist for Claude Code, Codex, Cursor, OpenCode, and Antigravity, and the setup path does not require a separate DB service or mandatory GPU dependency.
+
+### Phase 2: Namespace Model
+
+**Goal:** Make memory safe and useful across one project and all projects simultaneously through explicit namespaces and merge rules.
+
+**Status:** Complete (2026-03-25)
+
+**Requirements:** `SCP-01`, `SCP-02`, `SCP-03`, `SCP-04`
+
+**UI hint:** no
+
+**Success criteria:**
+1. The current repository resolves to a deterministic project memory namespace.
+2. A machine-wide global namespace exists for reusable cross-project knowledge.
+3. Search can run in `project`, `global`, and `hybrid` modes with documented precedence.
+4. Every result carries scope and origin metadata so agents can tell where the memory came from.
+
+### Phase 3: Markdown Ingestion
+
+**Goal:** Convert Markdown knowledge into stable, indexed memory blocks with deterministic provenance and incremental refresh behavior.
+
+**Status:** Complete (2026-03-26)
+
+**Requirements:** `ING-01`, `ING-02`, `ING-03`
+
+**UI hint:** no
+
+**Success criteria:**
+1. User can point the server at one or more Markdown directories for indexing.
+2. Files are split into stable blocks with reproducible block IDs and source metadata.
+3. Reindexing changed content updates affected blocks without rebuilding untouched content.
+4. The index persists locally between sessions.
+
+### Phase 4: Compressed Retrieval
+
+**Goal:** Let agents retrieve compact high-signal memory results with clear provenance while avoiding default raw-file dumps.
+
+**Status:** Complete (2026-03-26)
+
+**Requirements:** `RET-01`, `RET-02`, `SAFE-01`, `SAFE-02`
+
+**UI hint:** no
+
+**Success criteria:**
+1. Semantic search returns relevant blocks with score, path, and block ID.
+2. Agents can request compressed context cards that preserve meaning and traceability.
+3. Every retrieval result clearly points back to the original source block.
+4. Large raw context is not returned unless explicitly requested through a hydration path.
+
+### Phase 5: Hydration and Write-Back
+
+**Goal:** Recover fuller local context when compression is insufficient and persist new learnings for future sessions.
+
+**Status:** Complete (2026-03-26)
+
+**Requirements:** `RET-03`, `RET-04`, `MEM-01`, `MEM-02`
+
+**UI hint:** no
+
+**Success criteria:**
+1. Agent can hydrate a fuller block or excerpt when the compressed card is insufficient.
+2. Agent can request neighboring or related blocks to restore local context.
+3. Agent can save important notes or decisions into persistent memory with metadata.
+4. Saved notes become searchable alongside the original Markdown corpus.
+
+### Phase 6: Hardening and Adoption
+
+**Goal:** Make the system safe to adopt in day-to-day work through observability, verification, and operator-facing documentation.
+
+**Status:** Complete (2026-03-26)
+
+**Requirements:** `OPS-01`, `OPS-02`
+
+**UI hint:** no
+
+**Success criteria:**
+1. User can inspect server health, index freshness, and basic storage statistics.
+2. A documented smoke test validates install, indexing, search, and hydration end-to-end.
+3. The integration guide is simple enough for a new project to adopt without reverse engineering.
+4. Common failure modes are documented with first-response troubleshooting steps.
+
+### Phase 7: Knowledge-Base Hygiene (Quick Extension)
+
+**Goal:** Add a lightweight maintenance loop for agent-managed markdown wikis so broken links, orphan pages, and duplicate titles are visible before they degrade retrieval quality.
+
+**Status:** Complete (2026-04-03, quick task `260403-fe0`)
+
+**Requirements:** `KBL-01`, `KBL-02`, `KBL-03`
+
+**UI hint:** no
+
+**Success criteria:**
+1. MCP server exposes `lint_knowledge_base(...)` in the stable tool catalog.
+2. Lint reports broken internal links, orphan candidates, and duplicate normalized titles with bounded payload size.
+3. Lint can run against explicit `paths` or already registered markdown roots without re-indexing.
+
+## Coverage Check
+
+- All v1 requirements map to exactly one phase.
+- Усі v1-вимоги замаплено рівно на одну фазу.
+- The roadmap is biased toward fast adoption and minimal deployment friction.
+- Roadmap навмисно зміщений у бік швидкого adoption і мінімального тертя при розгортанні.
+- Post-v1 quick extensions can ship as focused slices without reopening the full milestone lifecycle.
+
+### Phase 8: Memory resilience, migration stats, release rollout, and client refresh
+
+**Goal:** Make upgrades safe, keep context retrieval honest, surface durable savings metrics, and ensure the released binary is the one local agent clients actually execute.
+
+**Status:** Complete (2026-04-03)
+
+**Requirements:** `OPS-01`, `OPS-02`
+**Depends on:** Phase 7
+**Plans:** 1/1 plans complete
+
+Plans:
+- [x] `08-01` Version-aware manifests, savings telemetry, smoke/docs refresh, and release rollout (completed 2026-04-03)
+
+**Success criteria:**
+1. Search and hydration auto-refresh stale derived indexes after a retrieval/markdown format mismatch instead of serving outdated context.
+2. Usage telemetry persists outside project/global memory and exposes byte/token savings plus bounded milestone headlines without polluting retrieval context.
+3. README, smoke checklist, and client fixtures match the new `v0.3.0` contract and explain the savings value clearly.
+4. The shared local MCP binary can be refreshed in place for Claude Code, Codex, Gemini, and OpenCode so live clients pick up the release.
+
+### Phase 9: Project-Scoped Encrypted Secrets Vault
+
+**Goal:** Give AI agents a safe place to persist project credentials (SSH, DB DSN, API tokens) across sessions and reboots, encrypted at rest, project-scoped, fully isolated from any retrieval path.
+
+**Status:** Complete (2026-05-25, shipped as `v0.7.0`)
+
+**Requirements:** `VLT-01`, `VLT-02`, `VLT-03`, `VLT-04`, `VLT-05`, `VLT-06`
+**Depends on:** Phase 8
+**Plans:** 3/3 plans complete
+
+Plans:
+- [x] `09-01` Cryptographic foundation, key resolver, secrets store, audit log (Wave 1, 2026-05-25)
+- [x] `09-02` Migration runner integration, MCP tool surface, indexer/lint/retrieval hardening (Wave 2, 2026-05-25)
+- [x] `09-03` Smoke test extension, bilingual docs, CHANGELOG, client fixture refresh (Wave 3, 2026-05-25)
+
+**Success criteria:**
+1. `set_secret` / `get_secret` round-trips survive daemon restart and machine reboot via OS keyring or env-passphrase fallback.
+2. `semantic_search`, `hydrate`, and `lint_knowledge_base` never see secret values; indexer refuses any `secrets/` directory traversal.
+3. Migration provisions an empty per-project vault for every existing `~/.turbo-quant-memory/projects/*` directory on first daemon start after upgrade; idempotent.
+4. Audit log records every secret access by `(timestamp, project_id, action, name)` with no value leakage; tool count grows `14 -> 18` and bilingual docs cover the threat model and setup contract.
+
+---
+*Last updated: 2026-05-25 with Phase 9 planning*