@cchez/memory-mcp 1.0.0

package/dist/tools/episode.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { MEMORY_TYPES, storeMemory } from "./store.js";
+const episodeMemorySchema = z.object({
+    content: z.string().min(1).describe("从 episode 中提炼出的可复用记忆"),
+    memory_type: z.enum(MEMORY_TYPES).describe("该条记忆的类型"),
+    tags: z.array(z.string()).optional().describe("该条记忆的 tags"),
+    confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .default(0.7)
+        .describe("该条记忆可信度，默认 0.7"),
+});
+export const captureEpisodeSchema = z.object({
+    episode_id: z.string().min(1).describe("任务/调试 episode ID，由 agent 或调用方生成"),
+    source: z.string().min(1).describe("episode 来源，如 agent/claude-code"),
+    summary: z
+        .string()
+        .min(1)
+        .describe("episode 摘要：问题、关键尝试、最终结论；不会自动存 raw trace"),
+    observations: z
+        .array(episodeMemorySchema)
+        .min(1)
+        .max(10)
+        .describe("确认值得长期保存的结构化观察，最多 10 条"),
+    related_ids: z.array(z.string()).optional().describe("该 episode 关联的已有记忆 ID"),
+});
+export async function captureEpisodeTool(input) {
+    const stored = [];
+    const episodeSummary = await storeMemory({
+        content: `Episode ${input.episode_id}: ${input.summary}`,
+        source: input.source,
+        memory_type: "summary",
+        tags: ["episode", ...(input.related_ids ?? [])],
+        status: "active",
+        confidence: 0.7,
+        episode_id: input.episode_id,
+        related_ids: input.related_ids,
+    });
+    stored.push({
+        id: episodeSummary.id,
+        collection: episodeSummary.collection,
+        memory_type: "summary",
+    });
+    for (const observation of input.observations) {
+        const result = await storeMemory({
+            content: observation.content,
+            source: input.source,
+            memory_type: observation.memory_type,
+            tags: observation.tags,
+            status: "active",
+            confidence: observation.confidence,
+            episode_id: input.episode_id,
+            related_ids: input.related_ids,
+            last_verified_at: new Date().toISOString(),
+        });
+        stored.push({
+            id: result.id,
+            collection: result.collection,
+            memory_type: observation.memory_type,
+        });
+    }
+    return { episode_id: input.episode_id, stored };
+}

package/dist/tools/list.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { listMemories } from "../qdrant.js";
+import { MEMORY_TYPES } from "./store.js";
+export const listMemoriesSchema = z.object({
+    collection: z
+        .enum(["coding", "workspace"])
+        .describe("目标 collection：coding=技术记忆, workspace=团队记忆"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(20)
+        .describe("返回条数，默认 20，最大 100"),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .default(0)
+        .describe("分页偏移量"),
+    source: z.string().optional().describe("按来源过滤"),
+    memory_type: z
+        .enum(MEMORY_TYPES)
+        .optional()
+        .describe("按类型过滤：rule / decision / fact / summary / preference"),
+    include_inactive: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("是否包含 superseded/deprecated 记忆，默认 false"),
+});
+export async function listMemoriesTool(input) {
+    const { collection, limit, offset, source, memory_type, include_inactive } = input;
+    return listMemories(collection, limit, offset, source, memory_type, include_inactive);
+}

package/dist/tools/search.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { getEmbeddingProvider } from "../embedding.js";
+import { searchMemory } from "../qdrant.js";
+import { MEMORY_TYPES } from "./store.js";
+const COLLECTION_NAMES = ["coding", "workspace"];
+const SEARCH_MODES = ["vector", "keyword", "hybrid"];
+export const searchMemorySchema = z.object({
+    query: z.string().min(1).describe("自然语言搜索查询"),
+    collections: z
+        .array(z.enum(COLLECTION_NAMES))
+        .optional()
+        .describe("搜索范围：['coding']仅技术记忆, ['workspace']仅团队记忆, 省略则同时搜两个"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .optional()
+        .default(5)
+        .describe("返回结果数量，默认 5"),
+    source: z.string().optional().describe("按来源过滤，如 slack/channel-name"),
+    score_threshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("最低相似度阈值 (0-1)，过滤低相关结果"),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("按标签过滤，所有指定标签都必须匹配"),
+    memory_type: z
+        .enum(MEMORY_TYPES)
+        .optional()
+        .describe("按类型过滤：rule / decision / fact / summary / preference"),
+    include_inactive: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("是否包含 superseded/deprecated 记忆，默认 false"),
+    mode: z
+        .enum(SEARCH_MODES)
+        .optional()
+        .default("hybrid")
+        .describe("检索模式：vector 仅语义检索，keyword 仅关键词检索，hybrid 混合检索（默认）"),
+    use_recency: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("是否对 fact/summary/preference 应用时间新鲜度加权，默认 true"),
+    use_mmr: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("是否使用 MMR 降低重复结果，默认 true"),
+});
+export async function searchMemoryTool(input) {
+    const { query, collections, limit, source, score_threshold, tags, memory_type, include_inactive, mode, use_recency, use_mmr, } = input;
+    const cols = collections ?? ["coding", "workspace"];
+    const vector = mode === "keyword" ? undefined : await getEmbeddingProvider().embed(query);
+    const results = await searchMemory({
+        vector,
+        query,
+        collections: cols,
+        limit,
+        sourceFilter: source,
+        scoreThreshold: score_threshold,
+        tagsFilter: tags,
+        memoryTypeFilter: memory_type,
+        includeInactive: include_inactive,
+        mode,
+        useRecency: use_recency,
+        useMmr: use_mmr,
+    });
+    return results.map((r) => ({
+        id: r.id,
+        content: r.content,
+        source: r.source,
+        memory_type: r.memory_type,
+        collection: r.collection,
+        tags: r.tags,
+        score: r.score,
+        vector_score: r.vector_score,
+        keyword_score: r.keyword_score,
+        recency_score: r.recency_score,
+        status: r.status,
+        created_at: r.created_at,
+        updated_at: r.updated_at,
+        supersedes: r.supersedes,
+        superseded_by: r.superseded_by,
+        correction_reason: r.correction_reason,
+        confidence: r.confidence,
+        episode_id: r.episode_id,
+        related_ids: r.related_ids,
+        valid_until: r.valid_until,
+        last_verified_at: r.last_verified_at,
+    }));
+}

package/dist/tools/store.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { createHash } from "crypto";
+import { getEmbeddingProvider } from "../embedding.js";
+import { upsertMemory, collectionForType, COLLECTIONS } from "../qdrant.js";
+export const MEMORY_TYPES = ["rule", "decision", "fact", "summary", "preference"];
+export const MEMORY_STATUSES = ["active", "superseded", "deprecated"];
+export const storeMemorySchema = z.object({
+    content: z.string().min(1).describe("知识内容（摘要或原文）"),
+    source: z.string().min(1).describe("来源，如 slack/pod-pay-pilots 或 agent/claude-code"),
+    memory_type: z
+        .enum(MEMORY_TYPES)
+        .describe("记忆类型 — coding collection: rule(编码规则/约束), decision(技术决策), preference(工具偏好); workspace collection: fact(团队事实/状态), summary(Slack/Confluence摘要)"),
+    tags: z.array(z.string()).optional().describe("可选标签列表"),
+    status: z
+        .enum(MEMORY_STATUSES)
+        .optional()
+        .default("active")
+        .describe("记忆生命周期状态，默认 active"),
+    confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("记忆可信度 0-1，用于后续审计和重打分"),
+    episode_id: z
+        .string()
+        .optional()
+        .describe("产生该记忆的 episode/task ID"),
+    related_ids: z
+        .array(z.string())
+        .optional()
+        .describe("相关记忆 ID 列表"),
+    supersedes: z
+        .string()
+        .optional()
+        .describe("该记忆修订/替代的旧记忆 ID"),
+    correction_reason: z
+        .string()
+        .optional()
+        .describe("修订原因，通常来自用户纠正或事实过期"),
+    valid_until: z
+        .string()
+        .optional()
+        .describe("事实类记忆的有效期 ISO 时间"),
+    last_verified_at: z
+        .string()
+        .optional()
+        .describe("该记忆最后被验证的 ISO 时间"),
+});
+export async function storeMemory(input) {
+    const { content, source, memory_type, tags, status, confidence, episode_id, related_ids, supersedes, correction_reason, valid_until, last_verified_at, } = input;
+    const id = createHash("sha256").update(content).digest("hex").slice(0, 32);
+    const embedder = getEmbeddingProvider();
+    const vector = await embedder.embed(content);
+    await upsertMemory(id, vector, {
+        content,
+        source,
+        memory_type,
+        tags,
+        status,
+        confidence,
+        episode_id,
+        related_ids,
+        supersedes,
+        correction_reason,
+        valid_until,
+        last_verified_at,
+        created_at: new Date().toISOString(),
+    });
+    return { id, collection: COLLECTIONS[collectionForType(memory_type)] };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@cchez/memory-mcp",
+  "version": "1.0.0",
+  "description": "AI memory MCP server with Qdrant vector storage and Ollama/OpenAI embeddings",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "memory-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "db/docker-compose.yml",
+    "db/.env.example",
+    "README.md",
+    "DESIGN.md"
+  ],
+  "scripts": {
+    "dev": "node --env-file=.env ./node_modules/tsx/dist/cli.mjs src/index.ts",
+    "dev:server": "node --env-file=.env ./node_modules/tsx/dist/cli.mjs src/server.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "start:server": "node dist/server.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai-agent",
+    "qdrant",
+    "ollama",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miuid/mcps.git",
+    "directory": "memory-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/miuid/mcps/issues"
+  },
+  "homepage": "https://github.com/miuid/mcps/tree/main/memory-mcp#readme",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@qdrant/js-client-rest": "^1.9.0",
+    "express": "^4.18.2",
+    "openai": "^4.47.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.12.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.4.4"
+  }
+}

package/skills/memory-correct/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: memory-correct
+description: >
+  Correct, revise, deprecate, or supersede existing memory mcp records when the
+  user says a stored memory is wrong/stale or new evidence contradicts it. Use
+  correct_memory to preserve an auditable revision chain instead of deleting and
+  re-saving. Do not use for brand-new unrelated memories; use memory-save.
+---
+
+# Memory Correct Skill
+
+## Purpose
+
+Keep memory trustworthy. A stale wrong memory is worse than no memory because
+future agents will confidently apply bad context. Corrections should preserve
+history while making the new truth the default search result.
+
+**Announce at start:** "Correcting memory."
+
+## When to Trigger
+
+Use this skill when:
+
+- The user says a retrieved memory is wrong, stale, misleading, or outdated
+- The user says "actually", "that's wrong", "update that memory", or "revise this"
+- New verified evidence contradicts an existing memory
+- A fact/config/rule changed and future searches should prefer the new version
+
+Do not use this skill when:
+
+- The new information is unrelated to an existing memory
+- The old record contains a secret or sensitive data that must be removed; use `delete_memory`
+- You cannot identify the old memory ID and collection after searching/listing
+
+## Step 1 — Find the Old Memory
+
+If the old memory ID and collection are already visible in the current result,
+use them. Otherwise call `search_memory` with `include_inactive: true` only if
+you are auditing prior corrections; default active search is enough for normal
+corrections.
+
+## Step 2 — Write Replacement Content
+
+Write `corrected_content` as a full standalone memory, not a diff.
+
+Good:
+
+```
+Airwallex KYC RFI template ID is kyc_rfi_v3_au as of 2026-06-28. The older
+kyc_rfi_v2_au value is deprecated.
+```
+
+Bad:
+
+```
+Actually it is v3.
+```
+
+## Step 3 — Call `correct_memory`
+
+Use:
+
+- `id`: old memory ID
+- `collection`: old memory collection
+- `corrected_content`: replacement memory
+- `correction_reason`: short reason, e.g. "user corrected stale template ID"
+- `confidence`: `0.9` for user-confirmed corrections; lower if inferred
+
+Omit `source`, `memory_type`, and `tags` when the old values are still correct.
+Override them only when the classification itself was wrong.
+
+## Step 4 — Confirm Briefly
+
+Tell the user the old memory was superseded by the new memory:
+
+> "Updated memory. Old ID `[old_id]` is superseded by `[new_id]`."
+
+## Self-Check
+
+- [ ] Did you identify the old memory ID and collection?
+- [ ] Is the replacement content standalone and future-readable?
+- [ ] Did you use `correct_memory`, not delete + store?
+- [ ] Did you preserve audit history unless deletion was required for safety?

package/skills/memory-save/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: memory-save
+description: >
+  Save valuable learnings, decisions, rules, or facts to the memory mcp
+  knowledge base. Triggers automatically when the agent discovers something
+  worth preserving: a coding constraint, an architectural decision, a resolved
+  ambiguity, a team process, or a configuration fact. Also triggers when the
+  user explicitly asks to save, remember, or store something. Do NOT save
+  trivial, transient, or already-known information. If the user corrects or
+  invalidates an existing memory, use correct_memory rather than delete + store.
+---
+
+# Memory Save Skill
+
+## Purpose
+
+Capture knowledge that would otherwise be lost between sessions. The knowledge
+base is only as useful as what gets put into it. This skill enforces quality
+over quantity — save things that are non-obvious, durable, and reusable.
+
+**Announce at start:** "Saving to memory."
+
+---
+
+## When to Trigger
+
+**Automatic triggers (save without being asked):**
+- A coding rule, constraint, or convention is discovered or confirmed
+  ("methods must stay under complexity 15 or CI fails")
+- An architectural or technology decision is made or ratified
+  ("we chose Qdrant over pgvector because of Docker-friendliness")
+- A configuration fact is established that future agents will need
+  ("Airwallex RFI template ID for KYC is ...")
+- An ambiguity is resolved that took effort to figure out
+  ("the `source` field format is `system/channel-name`")
+- The user says "remember this", "save this", "store this", "note this down"
+
+**Correction triggers (use `correct_memory`, not `store_memory`):**
+- The user says a retrieved memory is wrong, outdated, misleading, or no longer true
+- New evidence contradicts an existing memory found during `search_memory`
+- A rule, fact, or decision has changed but the old memory should remain auditable
+- The user says "update that memory", "revise this", "actually X", or "that's wrong"
+
+**Do NOT save:**
+- Things already in the knowledge base (check first if unsure)
+- Transient task state ("currently working on PR #123")
+- General knowledge not specific to this project/team
+- Unverified assumptions or guesses
+- Sensitive credentials or secrets
+
+If a correction trigger fires, first identify the old memory ID and collection
+from the search/list result, then call `correct_memory` with the replacement
+content and a short `correction_reason`. Do not call `delete_memory` for normal
+corrections; deletion is only for sensitive, duplicated, or intentionally
+removed records.
+
+---
+
+## Step 1 — Assess Save Worthiness
+
+Before saving, answer these three questions:
+
+1. **Is it durable?** Will this still be true / relevant in 3+ months?
+   - Rule: "complexity ≤ 15" → yes
+   - Task state: "fixing bug in PR #42" → no
+
+2. **Is it non-obvious?** Would a new engineer or agent know this without being told?
+   - Config fact: "Airwallex uses hosted flow, not redirect" → yes
+   - General fact: "TypeScript supports generics" → no
+
+3. **Is it actionable?** Does knowing this change how work gets done?
+   - Decision: "use SHA-256 content hash as Qdrant point ID for dedup" → yes
+   - Meeting note: "we had standup at 9:30" → no
+
+If all three are yes → save. If any is no → skip (or ask user if unsure).
+
+---
+
+## Step 2 — Classify the Memory
+
+Choose the correct `memory_type`:
+
+| Type | When to use | Collection |
+|---|---|---|
+| `rule` | Coding constraints, CI rules, style enforcements, hard limits | `coding` |
+| `decision` | Architecture choices, technology selections, design tradeoffs | `coding` |
+| `preference` | Team/user preferences, conventions, soft defaults | `coding` |
+| `fact` | Current state, configuration values, team facts, integration details | `workspace` |
+| `summary` | Distilled summaries of longer discussions, Slack threads, meetings | `workspace` |
+
+The collection is auto-routed by `memory_type` — you don't need to specify it.
+
+---
+
+## Step 3 — Write Good Content
+
+The `content` field is what gets embedded and searched. Write it for future
+retrieval, not for the current moment.
+
+**Good content:**
+- Starts with the key fact/rule/decision upfront
+- Includes enough context to be understood standalone (no "as mentioned above")
+- Uses specific names, numbers, and system names where relevant
+- Is 1–5 sentences: dense but not padded
+
+**Bad content:**
+- "We decided X" (vague — decided what exactly, and why?)
+- A dump of raw Slack messages (noise drowns signal)
+- A single word or phrase (not enough context for semantic search)
+
+**Template by type:**
+
+```
+rule:
+"[Rule statement]. Applies to [scope]. Reason: [why this rule exists].
+ Consequence of violation: [what breaks]."
+
+decision:
+"Decision: [what was decided]. Context: [why this decision was needed].
+ Rationale: [key reason(s)]. Alternatives rejected: [if relevant]."
+
+fact:
+"[System/entity]: [specific fact]. As of [date if time-sensitive].
+ Source: [where this came from]."
+
+summary:
+"[Topic] discussion summary ([date/channel]):
+ Key points: [1-3 bullets]. Decisions/actions: [if any]."
+
+preference:
+"[Team/user] prefers [specific preference] for [context].
+ Reason: [if known]."
+```
+
+---
+
+## Step 4 — Choose Tags
+
+Tags are optional but improve filtered retrieval. Pick 2–5 specific tags:
+
+- Use existing tag vocabulary if you've seen tags in prior search results
+- Prefer specific over generic: `rfi-webhook` over `webhook`
+- Include: system names, feature names, ticket IDs, technology names
+- Always include the domain: `payments`, `onboarding`, `billing`, etc.
+
+---
+
+## Step 5 — Execute Save
+
+If this is correcting an existing memory, skip this step and use Step 5b.
+
+Call `store_memory` with:
+- `content`: written per Step 3 template
+- `source`: `agent/claude-code` for agent-discovered learnings;
+            `user/manual` for user-requested saves;
+            `slack/<channel>` / `confluence/<page>` for external source ingestion
+- `memory_type`: from Step 2
+- `tags`: from Step 4
+
+The tool returns `{ id, collection }`. Note which collection it went to —
+confirm it matches the expected routing from Step 2.
+
+**If `store_memory` returns the same ID as a previous save**, the content was
+identical — this is a silent dedup (idempotent upsert). That's correct behaviour.
+
+## Step 5b — Execute Correction
+
+Call `correct_memory` when an old memory should be revised but kept auditable:
+
+- `id`: old memory ID
+- `collection`: old memory collection (`coding` or `workspace`)
+- `corrected_content`: full replacement memory, standalone and future-readable
+- `correction_reason`: short reason, e.g. "user corrected stale config value"
+- `memory_type`, `source`, `tags`: optional; omit to inherit from old memory
+- `confidence`: use `0.9` for user-confirmed corrections; lower it if inferred
+
+`correct_memory` writes a new active memory and marks the old one as
+`superseded`. Future searches hide the superseded memory by default; audit flows
+can pass `include_inactive: true`.
+
+---
+
+## Step 6 — Confirm to User
+
+For **automatic saves** (agent-initiated), confirm briefly:
+
+> "Saved to memory [collection/type]: [one-line summary of what was saved]."
+
+For **manual saves** (user asked), confirm with the ID in case they need to delete it later:
+
+> "Saved. ID: `[id]`, collection: `[collection]`, type: `[memory_type]`."
+
+For **corrections**, confirm both sides of the revision chain:
+
+> "Updated memory. Old ID `[old_id]` is superseded by `[new_id]`."
+
+Do not ask for confirmation before saving — act, then report. If the user
+wants to remove it, they can use `delete_memory(id, collection)`.
+
+---
+
+## Self-Check Before Finishing
+
+- [ ] Did the content pass all three save-worthiness tests (durable, non-obvious, actionable)?
+- [ ] Is `memory_type` correctly classified (not just "summary" for everything)?
+- [ ] Is `content` written for future retrieval (standalone, specific, dense)?
+- [ ] If this revised an existing memory, did you use `correct_memory` instead of delete + store?
+- [ ] Was the save confirmed to the user?
+- [ ] For automatic saves: did you save silently during work rather than interrupting flow?