@cchez/memory-mcp 1.0.0

package/DESIGN.md

@@ -0,0 +1,188 @@
+# Memory MCP — Design Document
+
+## Purpose
+
+A persistent, semantic memory store for AI agents. Agents working on the same codebase or within the same team can read and write shared knowledge across sessions: coding rules discovered during development, architecture decisions, team discussions from Slack, and project facts. The goal is to eliminate repeated context re-explanation and give agents access to learnings that accumulate over time.
+
+---
+
+## Core Design Decisions
+
+### 1. Vector storage: Qdrant
+
+Qdrant is the vector database. Chosen over alternatives because:
+- Written in Rust — high throughput, low latency on commodity hardware
+- Rich payload filtering (filter by `source`, `tags`, `memory_type` in a single query)
+- Clean REST + gRPC API, well-maintained Docker image
+- Snapshot API simplifies backup and cross-machine migration
+- No operational overhead vs distributed options (Milvus, Weaviate)
+
+pgvector was considered but rejected: SQL join overhead is unnecessary when the only query pattern is ANN search + metadata filter.
+
+### 2. Embedding model: Ollama bge-m3
+
+**bge-m3** (BAAI, 1024-dim, ~1.1 GB) runs locally via Ollama.
+
+Selected over alternatives:
+
+| Model | Dims | Size | Chinese | Decision |
+|---|---|---|---|---|
+| nomic-embed-text | 768 | ~300MB | near-zero | Rejected — too weak for Chinese content |
+| text-embedding-3-small | 1536 | API | excellent | Rejected — sends data to OpenAI, ongoing cost |
+| bge-m3 | 1024 | ~1.1GB | SOTA | **Selected** |
+| qwen3-embedding:8b | 4096 | ~16GB | #1 MTEB | Rejected — requires GPU, too heavy for dev machines |
+
+OpenAI is still supported as a fallback via `EMBEDDING_PROVIDER=openai`.
+
+**Critical constraint:** The embedding model is locked at collection creation time. All stored vectors must use the same model and dimension. Switching models requires a full re-embed of all data (`scripts/migrate-reembed.ts`).
+
+### 3. Two collections, auto-routed by `memory_type`
+
+A single collection mixing Slack summaries with coding rules degrades search quality — the semantic spaces of "team communication" and "technical constraints" are different enough to pollute results when merged.
+
+Two collections are maintained:
+
+```
+coding     ← rule, decision, preference
+workspace  ← fact, summary
+```
+
+Routing is automatic: `store_memory` reads `memory_type` and writes to the correct collection. Agents never specify a collection when writing. Search defaults to both collections, with an optional `collections` filter.
+
+### 4. Content-hash deduplication
+
+Point IDs in Qdrant are the first 32 hex characters of SHA-256(`content`). Writing identical content twice produces one record (Qdrant upsert is idempotent). This prevents retrieval pollution from repeated ingestion of the same Slack message or rule.
+
+### 5. MCP as the agent interface
+
+The MCP stdio server exposes four tools:
+
+| Tool | Purpose |
+|---|---|
+| `store_memory` | Write a memory (auto-routed, deduplicated) |
+| `search_memory` | Hybrid vector + keyword + recency search across one or both collections |
+| `delete_memory` | Remove a record by ID |
+| `list_memories` | Paginated browse for audit / ID lookup |
+| `correct_memory` | Supersede an incorrect/stale memory with a corrected replacement |
+| `capture_episode` | Opt-in episode summary and durable observation capture |
+
+MCP was chosen over a plain REST API for the agent interface because:
+- Tool descriptions are embedded in the protocol — agents discover capabilities without configuration
+- Works with Claude Code, Claude Desktop, and any MCP-compliant host without custom integration
+- Zod schema validation on all inputs prevents malformed queries reaching Qdrant
+
+A separate HTTP ingest server (`server.ts`) handles bulk writes from automated pipelines (e.g. scheduled Slack summarisation jobs) where MCP overhead is unnecessary. It uses Bearer token auth and returns partial-success responses (HTTP 207) when some items in a batch fail.
+
+### 6. Self-contained Docker stack
+
+Qdrant and Ollama both run as Docker containers. The MCP server runs on the host (as a stdio process spawned by the agent host). This means:
+- `docker compose up -d` in `db/` is the only infrastructure setup step
+- Data persists in bind mounts (`db/qdrant_data/`, `db/ollama_data/`)
+- Moving to a new machine = copy the folder + `docker compose up -d`
+- No cloud dependencies, no API keys required for the default configuration
+
+---
+
+## Data Model
+
+Each memory is stored as a Qdrant point:
+
+```typescript
+{
+  id: string,          // SHA-256 hash of content (first 32 hex chars)
+  vector: number[],    // 1024-dim embedding from bge-m3
+  payload: {
+    content: string,       // The knowledge text
+    source: string,        // Origin: "slack/channel", "agent/claude-code", etc.
+    memory_type: MemoryType, // "rule" | "decision" | "preference" | "fact" | "summary"
+    tags: string[],        // Optional: specific tags for filtered retrieval
+    created_at: string,    // ISO 8601 timestamp
+    updated_at: string,    // ISO 8601 timestamp
+    status: "active" | "superseded" | "deprecated",
+    supersedes?: string,       // old memory ID replaced by this memory
+    superseded_by?: string,    // new memory ID that replaced this memory
+    correction_reason?: string,
+    confidence?: number,       // 0-1 audit signal
+    episode_id?: string,       // task/debug episode that produced this memory
+    related_ids?: string[],
+    valid_until?: string,
+    last_verified_at?: string,
+  }
+}
+```
+
+### `memory_type` semantics
+
+| Type | Collection | Meaning | Durability |
+|---|---|---|---|
+| `rule` | coding | Hard constraint (CI rule, style enforcement, hard limit) | Long-lived |
+| `decision` | coding | Architecture or technology choice with rationale | Long-lived |
+| `preference` | coding | Soft convention or team preference | Medium |
+| `fact` | workspace | Current state: config values, team facts, integration details | Time-sensitive |
+| `summary` | workspace | Distilled summary of a discussion, meeting, or Slack thread | Time-sensitive |
+
+### `source` conventions
+
+```
+slack/<channel-name>          — from a Slack channel
+agent/claude-code             — discovered by Claude Code during development
+agent/<other-agent-name>      — discovered by another AI agent
+manual/<topic>                — manually provided by a human
+confluence/<page-title>       — from a Confluence page
+ci/<pipeline-name>            — from CI/CD output
+```
+
+---
+
+## Search Behaviour
+
+Search embeds the query with the same model, then runs lifecycle-aware hybrid retrieval:
+
+1. Query is embedded → 1024-dim vector
+2. Active memories are searched by default; `superseded` and `deprecated` records are excluded unless `include_inactive=true`
+3. Vector candidates come from Qdrant cosine similarity search
+4. Keyword candidates come from lexical matching over `content`, `source`, `memory_type`, `tags`, and `episode_id`
+5. Scores are blended from vector similarity, keyword score, and recency score; `rule` and `decision` do not decay, while `fact`, `summary`, and `preference` receive recency weighting
+6. MMR re-ranks merged candidates to reduce near-duplicate results
+7. Optional filters are applied: `source`, `tags`, `memory_type`, `score_threshold`
+
+Supported modes: `hybrid` (default), `vector`, and `keyword`. Recommended `score_threshold`: **0.5** for general search, **0.65** when precision matters.
+
+## Feedback Loop and Episodes
+
+`correct_memory` handles the correction loop: user or agent provides corrected content and a reason, the system writes a new active memory, marks the old record `superseded`, and links both sides via `supersedes` / `superseded_by`.
+
+`capture_episode` handles opt-in SDLC/debug memory. It stores a compact episode summary plus durable observations supplied by the caller. It intentionally does not capture raw conversation or tool traces; noisy automatic trace ingestion is out of scope.
+
+---
+
+## Agent Skills
+
+Two skills guide agent behaviour around memory:
+
+**`memory-search`** — triggers automatically when starting work on a feature, discussing architecture, or when the user asks to look something up. Chooses the right collection and filters, caps at two search attempts per topic, and applies results directly to work rather than just summarising them back.
+
+**`memory-save`** — triggers when a coding rule is discovered, a decision is ratified, or a configuration fact is established. Applies a three-question filter (durable? non-obvious? actionable?) before saving. Writes content in structured templates optimised for future semantic retrieval.
+
+Install both skills from `skills/` into `~/.claude/skills/`.
+
+---
+
+## Migration Scripts
+
+### `scripts/migrate.ts`
+
+One-time migration from the original single `knowledge` collection to the dual `coding`/`workspace` structure. Infers `memory_type` from `source` and `tags`. Copies vectors directly (no re-embed needed — same model, same dimensions).
+
+### `scripts/migrate-reembed.ts`
+
+Used when switching embedding models. Drops and recreates all collections at the new vector size, then re-embeds every record using the currently configured embedding provider. Supports dry-run mode (`MIGRATE_DRY_RUN=true`). Includes an Ollama health-check with retry so it works in automated environments where the model is still loading.
+
+---
+
+## What Is Not in Scope
+
+- **Multi-tenancy / ACLs:** All agents share the same collections. If per-user or per-team isolation is needed, implement separate collections with a naming convention (e.g. `coding_teamA`) and route via `source` filters.
+- **Chunking:** Long documents are stored as single vectors. Content over ~500 tokens will have degraded embedding quality. For long-form ingestion, chunk before calling `store_memory`.
+- **Raw trace capture:** The system does not automatically ingest full conversations or tool traces. Episode capture is explicit and summary-based.
+- **Background reflection / promotion:** There is no background agent that promotes short-term facts to long-term decisions without an explicit `capture_episode` or `store_memory` call.

package/README.md

@@ -0,0 +1,484 @@
+# Memory MCP
+
+A self-contained AI memory store for agents and developers. Stores coding rules, architecture decisions, team discussions, and project facts as semantic vectors. Any MCP-compatible agent can search and save memories across sessions.
+
+**Stack:** Qdrant (vector DB) + Ollama bge-m3 (embedding) + MCP stdio server — all containerised, zero cloud dependencies.
+
+---
+
+## Architecture
+
+```
+memory-mcp/
+├── db/
+│   ├── docker-compose.yml   # Qdrant + Ollama containers
+│   ├── .env.example         # Environment variable template
+│   ├── qdrant_data/         # Persisted vector data (gitignored)
+│   └── ollama_data/         # Persisted model cache (gitignored)
+├── src/
+│   ├── index.ts             # MCP stdio server
+│   ├── server.ts            # HTTP bulk-ingest server
+│   ├── embedding.ts         # Embedding provider abstraction (Ollama / OpenAI)
+│   ├── qdrant.ts            # Qdrant client — dual-collection, auto-routing
+│   └── tools/
+│       ├── store.ts         # store_memory tool
+│       ├── search.ts        # search_memory tool
+│       ├── delete.ts        # delete_memory tool
+│       ├── list.ts          # list_memories tool
+│       ├── correct.ts       # correct_memory tool — supersession chain
+│       └── episode.ts       # capture_episode tool — opt-in task summaries
+├── scripts/
+│   ├── migrate.ts           # One-time migration: old collection → coding/workspace
+│   └── migrate-reembed.ts   # Re-embed all data when switching embedding model
+└── skills/
+    ├── memory-search/       # Agent skill: when and how to search memory
+  ├── memory-save/         # Agent skill: when and how to save to memory
+  └── memory-correct/      # Agent skill: when and how to correct memory
+```
+
+### Collections
+
+Memories are auto-routed to one of two Qdrant collections based on `memory_type`:
+
+| Collection | memory_type values | Content |
+|---|---|---|
+| `coding` | `rule`, `decision`, `preference` | Coding constraints, architecture choices, tool preferences |
+| `workspace` | `fact`, `summary` | Team discussions, Slack summaries, project facts, config values |
+
+---
+
+## Quick Start
+
+### Step 1 — Start the database and embedding model
+
+```bash
+cd db
+docker compose up -d
+```
+
+This starts:
+- **Qdrant** on `http://localhost:6333` (vector database)
+- **Ollama** on `http://localhost:11434` (embedding server, auto-pulls `bge-m3` on first run)
+
+First run takes 1–2 minutes while bge-m3 (~1.1 GB) downloads. Check progress:
+
+```bash
+docker compose logs -f ollama
+```
+
+Verify both are ready:
+
+```bash
+curl http://localhost:6333/collections        # Qdrant
+curl http://localhost:11434/api/tags          # Ollama — should list bge-m3
+```
+
+> **Note:** If you have Ollama running locally on port 11434, stop it first to avoid port conflicts:
+> ```bash
+> killall ollama 2>/dev/null || true
+> ```
+
+### Step 2 — Configure environment
+
+```bash
+cp db/.env.example .env
+```
+
+The defaults work out of the box with the docker-compose setup. Edit `.env` only if you need to customise:
+
+```env
+QDRANT_URL=http://localhost:6333
+CODING_COLLECTION=coding
+WORKSPACE_COLLECTION=workspace
+
+EMBEDDING_PROVIDER=ollama          # or "openai"
+EMBEDDING_DIMENSIONS=1024          # must match the model (bge-m3 = 1024)
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=bge-m3
+
+# Only needed if EMBEDDING_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+
+INGEST_API_KEY=your-secret-key     # for HTTP bulk-ingest auth
+PORT=3000
+```
+
+### Step 3 — Install dependencies
+
+Only needed for local development from this repo:
+
+```bash
+npm install
+```
+
+### Step 4 — Wire up the MCP server
+
+For normal usage, run the MCP server via npm with `npx`. Add this to your Claude Code / Claude Desktop MCP config (`.claude/settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@cchez/memory-mcp@latest"
+      ],
+      "env": {
+        "QDRANT_URL": "http://localhost:6333",
+        "EMBEDDING_PROVIDER": "ollama",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "bge-m3",
+        "EMBEDDING_DIMENSIONS": "1024",
+        "CODING_COLLECTION": "coding",
+        "WORKSPACE_COLLECTION": "workspace"
+      }
+    }
+  }
+}
+```
+
+For local development before publishing, point the MCP host at the source file instead:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "/absolute/path/to/memory-mcp/node_modules/tsx/dist/cli.mjs",
+        "/absolute/path/to/memory-mcp/src/index.ts"
+      ],
+      "env": {
+        "QDRANT_URL": "http://localhost:6333",
+        "EMBEDDING_PROVIDER": "ollama",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "bge-m3",
+        "EMBEDDING_DIMENSIONS": "1024",
+        "CODING_COLLECTION": "coding",
+        "WORKSPACE_COLLECTION": "workspace"
+      }
+    }
+  }
+}
+```
+
+> **Why `node` instead of `npm run dev` for local development?** Some MCP hosts don't reliably pass the `cwd` field to the spawned process, causing npm to look for `package.json` in the wrong directory. Invoking `node` with absolute paths bypasses npm entirely and works regardless of working directory.
+
+Replace both `/absolute/path/to/memory-mcp` occurrences with the actual path to this repo (e.g. `/Users/you/projects/memory-mcp`).
+
+Restart Claude Code / Claude Desktop. The MCP tools will be available immediately.
+
+### Step 5 — Install agent skills (optional but recommended)
+
+Copy the skills into your Claude skills directory so agents automatically know when to search and save memory:
+
+```bash
+cp -r skills/memory-search ~/.claude/skills/
+cp -r skills/memory-save ~/.claude/skills/
+cp -r skills/memory-correct ~/.claude/skills/
+```
+
+Restart Claude Code to pick up the new skills.
+
+---
+
+## Publishing to npmjs
+
+The package is configured as `@cchez/memory-mcp` and exposes one executable bin, `memory-mcp`, backed by `dist/index.js`. The package uses a `files` allowlist so local Qdrant/Ollama data is not published.
+
+Before publishing:
+
+```bash
+npm run build
+npm run pack:dry-run
+```
+
+First-time publish for a scoped public package:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+After publish, agent configs can use:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@cchez/memory-mcp@latest"]
+}
+```
+
+The npm package only runs the MCP server. Qdrant and Ollama still need to be running separately, for example with `db/docker-compose.yml` from this repo.
+
+### Step 6 - Global instruction
+
+```
+# Memory
+
+知识库（memory mcp）是核心资产，通过 memory mcp 访问。
+
+## 搜索 — 先查再做
+
+开始任何任务前，先搜索知识库获取相关上下文：
+- 开始写代码或修 bug → 搜索是否有相关编码规则或约束
+- 讨论架构或技术选型 → 搜索是否有已有决策
+- 遇到项目、系统、集成的名称 → 搜索相关背景和配置事实
+- 用户问"我们之前怎么处理 X 的" → 搜索知识库，别靠猜
+
+搜索时设 `score_threshold: 0.5` 过滤低相关结果。不确定搜哪个 collection 就两个都搜（默认行为）。每个话题最多搜两次（换个措辞重试一次），没结果就停，不要死循环。
+
+## 保存 — 三问过滤
+
+发现以下信息时主动保存，不需要用户提醒：
+- 编码约束或规则（"方法复杂度不能超过 15，否则 CI 挂"）
+- 架构或技术选型决策（"选择了 Qdrant，原因是…"）
+- 配置事实（"Airwallex RFI KYC template ID 是 xxx"）
+- 解决了一个非显而易见的歧义
+
+用户说"记住这个"时，立即保存。
+
+保存前过三问：① 耐久？3 个月后还成立吗 ② 非显而易见？新人不会的知道吗 ③ 可复用？会影响下次工作吗。三问全是才保存。不保存：任务状态、短暂信息、众所周知的事实。
+
+## memory_type 分类
+
+| memory_type | 保存什么 | 自动路由到 |
+|---|---|---|
+| `rule` | 编码约束、CI 规则、强制规范 | coding |
+| `decision` | 技术选型、架构决策（含原因） | coding |
+| `preference` | 团队偏好、软性约定 | coding |
+| `fact` | 配置值、团队现状、集成细节 | workspace |
+| `summary` | Slack/会议/文档的提炼摘要 | workspace |
+
+collection 不需要手动指定，由 `memory_type` 自动路由。
+
+## source 格式
+
+`slack/<频道名>` / `agent/claude-code` / `confluence/<页面名>` / `manual/<主题>`
+
+## 删除过时记忆
+
+发现知识库中有错误或过期内容时，用 `correct_memory` 写入修订版并 supersede 旧记忆。只有敏感信息、重复垃圾、或确实不应保留审计历史的记录才用 `delete_memory(id, collection)`。
+```
+
+---
+
+## MCP Tools Reference
+
+### `store_memory`
+
+Save a piece of knowledge. Content with identical text is automatically deduplicated (idempotent upsert via SHA-256 hash).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `content` | string | yes | The knowledge to store (1–5 sentences, written for future retrieval) |
+| `source` | string | yes | Origin: `slack/channel-name`, `agent/claude-code`, `confluence/page-title`, `manual/...` |
+| `memory_type` | enum | yes | `rule` / `decision` / `preference` / `fact` / `summary` |
+| `tags` | string[] | no | 2–5 specific tags for filtered retrieval |
+| `status` | enum | `active` | `active` / `superseded` / `deprecated` |
+| `confidence` | number | no | Confidence score 0–1 |
+| `episode_id` | string | no | Task/debug episode that produced the memory |
+| `related_ids` | string[] | no | Related memory IDs |
+| `supersedes` | string | no | Older memory ID replaced by this memory |
+| `valid_until` | string | no | ISO timestamp for time-sensitive facts |
+| `last_verified_at` | string | no | ISO timestamp for last verification |
+
+Returns: `{ id, collection }`
+
+### `search_memory`
+
+Hybrid search across one or both collections. The default `hybrid` mode combines vector similarity, exact keyword matching, light recency weighting, and MMR de-duplication. Superseded and deprecated memories are hidden unless explicitly requested.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `query` | string | — | Natural language query |
+| `collections` | array | both | `["coding"]`, `["workspace"]`, or omit for both |
+| `limit` | number | 5 | Max results (1–20) |
+| `score_threshold` | number | — | Min similarity 0–1 (recommended: 0.5) |
+| `memory_type` | enum | — | Filter by type |
+| `tags` | string[] | — | Filter — all specified tags must match |
+| `source` | string | — | Filter by exact source string |
+| `include_inactive` | boolean | false | Include `superseded` / `deprecated` memories |
+| `mode` | enum | `hybrid` | `vector`, `keyword`, or `hybrid` |
+| `use_recency` | boolean | true | Apply recency weighting to time-sensitive memories |
+| `use_mmr` | boolean | true | Reduce duplicate-looking results |
+
+Returns: array of `{ id, content, source, memory_type, collection, tags, score, vector_score, keyword_score, recency_score, status, created_at, updated_at, ...lifecycle_fields }`
+
+### `correct_memory`
+
+Create a corrected replacement for an existing memory. The old memory is marked `superseded`; the new memory is written as `active` with `supersedes` pointing at the old ID.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | yes | Old memory ID |
+| `collection` | enum | yes | Old memory collection: `coding` or `workspace` |
+| `corrected_content` | string | yes | Replacement memory content |
+| `correction_reason` | string | yes | Why the old memory is wrong/stale |
+| `source` | string | no | Defaults to old source |
+| `memory_type` | enum | no | Defaults to old type |
+| `tags` | string[] | no | Defaults to old tags |
+| `confidence` | number | no | Defaults to `0.9` |
+
+### `capture_episode`
+
+Opt-in capture for task/debug episodes. This does **not** ingest raw conversation or tool traces; callers provide a compact summary plus durable observations that passed a quality filter.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `episode_id` | string | yes | Task/debug episode identifier |
+| `source` | string | yes | Usually `agent/claude-code` or another agent source |
+| `summary` | string | yes | What happened, key attempts, final conclusion |
+| `observations` | array | yes | 1–10 structured memories with `content`, `memory_type`, optional `tags` and `confidence` |
+| `related_ids` | string[] | no | Existing memory IDs related to this episode |
+
+### `delete_memory`
+
+Delete a specific memory entry by ID.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | yes | ID returned by `store_memory` |
+| `collection` | enum | yes | `coding` or `workspace` |
+
+### `list_memories`
+
+Browse memory entries with pagination — useful for auditing or finding IDs.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `collection` | enum | — | `coding` or `workspace` (required) |
+| `limit` | number | 20 | Max results (1–100) |
+| `offset` | number | 0 | Pagination offset |
+| `source` | string | — | Filter by source |
+| `memory_type` | enum | — | Filter by type |
+| `include_inactive` | boolean | false | Include superseded/deprecated memories for audit |
+
+---
+
+## Example Prompts
+
+### Saving memories
+
+```
+Remember this rule: all service methods must have cyclomatic complexity ≤ 15,
+otherwise the CI pipeline fails. Source is agent/claude-code, type is rule,
+tags: ci, complexity, typescript.
+```
+
+```
+Save to memory: we decided to use SHA-256 content hash as the Qdrant point ID
+for deduplication. Same content written twice produces one record.
+Source: agent/claude-code, type: decision, tags: qdrant, deduplication, architecture.
+```
+
+```
+Note down: Airwallex RFI hosted flow KYC template ID is "kyc_rfi_v2_au".
+Source: manual/airwallex-config, type: fact, tags: airwallex, rfi, configuration.
+```
+
+### Searching memories
+
+```
+Search memory for any rules about code complexity limits.
+```
+
+```
+What do we know about our Airwallex integration configuration?
+Search the workspace collection.
+```
+
+```
+Find all architecture decisions we've made. Search coding collection,
+memory_type decision, score threshold 0.5.
+```
+
+```
+List everything in the coding collection so I can audit what rules are stored.
+```
+
+### Deleting stale memories
+
+```
+Delete memory id "a3f2b1c9..." from the workspace collection.
+```
+
+---
+
+## HTTP Bulk Ingest
+
+For automated pipelines (e.g. daily Slack summarisation jobs):
+
+```bash
+npm run dev:server
+```
+
+```bash
+curl -X POST http://localhost:3000/ingest \
+  -H "Authorization: Bearer <INGEST_API_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "memories": [
+      {
+        "content": "Pod Pay Pilots weekly update 2026-04-22: document upload UI refactor completed. UAT sign-off from Katrina Li.",
+        "source": "slack/pod-pay-pilots",
+        "memory_type": "summary",
+        "tags": ["weekly-update", "document-upload", "uat"]
+      },
+      {
+        "content": "Decision: LaunchDarkly flag AU_discoverability_beanie_events controls Beanie event emission for AU bill pay. Default off in production.",
+        "source": "slack/pod-pay-pilots-engineers",
+        "memory_type": "fact",
+        "tags": ["launchdarkly", "feature-flag", "au-bill-pay"]
+      }
+    ]
+  }'
+```
+
+Response (all succeeded):
+```json
+{ "stored": 2, "failed": 0, "succeeded": [{"index": 0, "id": "..."}, {"index": 1, "id": "..."}] }
+```
+
+Response (partial failure — HTTP 207):
+```json
+{ "stored": 1, "failed": 1, "succeeded": [...], "errors": [{"index": 1, "error": "..."}] }
+```
+
+Health check:
+```bash
+curl http://localhost:3000/health
+# {"status":"ok"}
+```
+
+---
+
+## Switching Embedding Models
+
+The embedding model is a **hard infrastructure decision** — all stored vectors must use the same model. To switch models:
+
+1. Update `.env`: set `OLLAMA_MODEL` (or `EMBEDDING_PROVIDER=openai`) and `EMBEDDING_DIMENSIONS`
+2. Run the re-embed migration:
+
+```bash
+# Dry-run first
+MIGRATE_DRY_RUN=true node --env-file=.env ./node_modules/tsx/dist/cli.mjs scripts/migrate-reembed.ts
+
+# Execute
+MIGRATE_DRY_RUN=false node --env-file=.env ./node_modules/tsx/dist/cli.mjs scripts/migrate-reembed.ts
+```
+
+This drops and recreates all collections at the new vector size, then re-embeds every stored record.
+
+---
+
+## Stop Services
+
+```bash
+cd db
+docker compose down          # stop containers, keep data
+docker compose down -v       # stop containers and delete all data
+```

package/db/.env.example

@@ -0,0 +1,16 @@
+QDRANT_URL=http://localhost:6333
+CODING_COLLECTION=coding
+WORKSPACE_COLLECTION=workspace
+
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_DIMENSIONS=1024
+
+# OpenAI (only if EMBEDDING_PROVIDER=openai)
+OPENAI_API_KEY=sk-...
+
+# Ollama — points to the ollama container in docker-compose
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=bge-m3
+
+INGEST_API_KEY=your-secret-key
+PORT=3000