@luisarg/memory-mcp 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,14 +1,12 @@
 import Schema from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
-
 //#region src/index.d.ts
-declare const name = "memory-mcp";
-interface Config {
+export declare const name = "memory-mcp";
+export interface Config {
   memoryPath: string;
   serverDir: string;
 }
-declare const Config: Schema<Config>;
-declare function apply(ctx: Context, config: Config): void;
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, apply, name };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;cAOa,IAAA;UAEI,MAAA;EAFJ,UAAI,EAAA,MAAA;EAEA,SAAM,EAAA,MAAA;AAKvB;AAwCgB,cAxCH,MAwCc,EAxCN,MAwCuB,CAxChB,MAwCsB,CAAA;iBAAlC,KAAA,MAAW,iBAAiB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;qBAQa;iBAEI;EACf;EACA;;qBAGW,QAAQ,OAAO;wBAwCZ,MAAM,KAAK,SAAS,QAAQ"}

package/dist/index.js

@@ -3,7 +3,109 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import Schema from "@deepseek-ai/schemastery";
-
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+//#region src/skills.ts
+/**
+* Bundled skills shipped in this package: `brain` (read the vault) and
+* `checkpoint` (capture a session into it).
+*
+* A provider rather than `ctx.skills.register()` on purpose. A registration
+* lands at the runtime rank, which outranks a user's own skill directories,
+* while BUNDLED_SKILL_RANK is the weakest rank in the local discovery table:
+* shipping at the weakest rank means a user who drops their own `brain` into
+* `~/.agents/skills` keeps winning the name. These are defaults, not a takeover.
+*
+* Each SKILL.md stays the single source of its own name, description and
+* usage guidance — the frontmatter is parsed here with the same `yaml`
+* dependency the harness's own filesystem provider uses, so the exact file that
+* ships in this package also works copied into a user skill root.
+*/
+/** Provider name registered on `ctx.skills`. */
+const SKILLS_PROVIDER = "memory-mcp-skills";
+/** Shipped skill directories, relative to the package root. */
+const SKILL_NAMES = ["brain", "checkpoint"];
+const SKILLS_ROOT = new URL("../skills/", import.meta.url);
+const INVOCATION = {
+	modelInvocable: true,
+	userInvocable: true
+};
+function skillUrl(name) {
+	return new URL(`${name}/SKILL.md`, SKILLS_ROOT);
+}
+function resourceBase(name) {
+	return {
+		kind: "directory",
+		path: fileURLToPath(new URL(`${name}/`, SKILLS_ROOT))
+	};
+}
+/** Split YAML frontmatter from the body, mirroring the harness filesystem provider. */
+function splitFrontmatter(raw) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+	if (match === null) throw new Error("SKILL.md has no YAML frontmatter");
+	const parsed = parse(match[1]);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new TypeError("SKILL.md frontmatter must be a YAML mapping");
+	return {
+		data: parsed,
+		body: raw.slice(match[0].length).trim()
+	};
+}
+function textField(data, key) {
+	const value = data[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/** Read one shipped skill, rejecting a file whose frontmatter disagrees with its directory. */
+async function loadSkill(name) {
+	const { data, body } = splitFrontmatter(await readFile(skillUrl(name), "utf8"));
+	const declared = textField(data, "name");
+	if (declared !== name) throw new Error(`skills/${name}/SKILL.md declares name "${declared ?? "(none)"}"`);
+	const description = textField(data, "description");
+	if (description === void 0) throw new Error(`skills/${name}/SKILL.md has no description`);
+	const whenToUse = textField(data, "whenToUse");
+	return {
+		frontmatter: {
+			name,
+			description,
+			...whenToUse === void 0 ? {} : { whenToUse }
+		},
+		body
+	};
+}
+/** Skills shipped as packaged Markdown assets. */
+const skillsProvider = {
+	name: SKILLS_PROVIDER,
+	async list() {
+		return await Promise.all(SKILL_NAMES.map(async (name) => {
+			const { frontmatter } = await loadSkill(name);
+			return {
+				...frontmatter,
+				path: fileURLToPath(skillUrl(name)),
+				invocation: INVOCATION,
+				source: "bundled",
+				provider: SKILLS_PROVIDER,
+				resourceBase: resourceBase(name),
+				rank: BUNDLED_SKILL_RANK,
+				locator: skillUrl(name)
+			};
+		}));
+	},
+	async get(candidate) {
+		const loaded = await loadSkill(candidate.name).catch(() => void 0);
+		if (loaded === void 0) return void 0;
+		const { frontmatter, body } = loaded;
+		return {
+			...frontmatter,
+			path: fileURLToPath(skillUrl(candidate.name)),
+			invocation: INVOCATION,
+			source: "bundled",
+			provider: SKILLS_PROVIDER,
+			resourceBase: resourceBase(candidate.name),
+			content: body
+		};
+	}
+};
+//#endregion
 //#region src/index.ts
 const name = "memory-mcp";
 const Config = Schema.object({
@@ -41,6 +143,9 @@ function ensureFile(target, bundled, file) {
 	return true;
 }
 function apply(ctx, config) {
+	ctx.inject(["skills"], (ctx) => {
+		ctx.skills.registerProvider(() => skillsProvider);
+	});
 	const serverDir = resolveUnderHome(config.serverDir, "memory-vault-server");
 	const memoryPath = resolveUnderHome(config.memoryPath, "memory-vault");
 	if (ensure(serverDir, join(packageRoot, "server"), "server.py")) console.log(`[memory-mcp] installed memory-vault-server -> ${serverDir}`);
@@ -49,7 +154,7 @@ function apply(ctx, config) {
 	for (const file of ["launcher.mjs", "requirements.txt"]) if (ensureFile(serverDir, bundled, file)) console.log(`[memory-mcp] installed ${file} -> ${serverDir}`);
 	if (!existsSync(join(serverDir, "server.py"))) console.warn(`[memory-mcp] memory-vault-server not found at ${serverDir} and not bundled — set DSH_MEMORY_SERVER_DIR (or run \`node scripts/bundle-assets.mjs\` in a checkout)`);
 }
-
 //#endregion
 export { Config, apply, name };
+
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Config: Schema<Config>"],"sources":["../src/index.ts"],"sourcesContent":["import { cpSync, existsSync, mkdirSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { dirname, isAbsolute, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { Context } from '@deepseek-ai/cordis'\nimport Schema from '@deepseek-ai/schemastery'\n\nexport const name = 'memory-mcp'\n\nexport interface Config {\n  memoryPath: string\n  serverDir: string\n}\n\nexport const Config: Schema<Config> = Schema.object({\n  memoryPath: Schema.string().default(process.env.DSH_MEMORY_PATH ?? ''),\n  serverDir: Schema.string().default(process.env.DSH_MEMORY_SERVER_DIR ?? ''),\n})\n\nconst packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))\n\n/** Harness home, resolved like the harness itself ($DSH_HOME, or ~/.dsh). */\nfunction dshHome(): string {\n  const env = process.env.DSH_HOME?.trim()\n  return env && env.length > 0 ? env : join(homedir(), '.dsh')\n}\n\n/** Absolute paths stay; empty/relative values resolve under the harness home. */\nfunction resolveUnderHome(value: string, segment: string): string {\n  const v = value.trim()\n  if (v.length === 0) return join(dshHome(), segment)\n  return isAbsolute(v) ? v : join(dshHome(), v)\n}\n\n/** Copy the bundled dir into `target` when `key` is missing there. */\nfunction ensure(target: string, bundled: string, key: string): boolean {\n  if (existsSync(join(target, key))) return false\n  if (!existsSync(bundled)) return false\n  mkdirSync(target, { recursive: true })\n  cpSync(bundled, target, { recursive: true })\n  return true\n}\n\n/** Copy one bundled file into `target` when missing (upgrades add files 0.1.1 → 0.1.2). */\nfunction ensureFile(target: string, bundled: string, file: string): boolean {\n  const dest = join(target, file)\n  if (existsSync(dest)) return false\n  const src = join(bundled, file)\n  if (!existsSync(src)) return false\n  mkdirSync(target, { recursive: true })\n  cpSync(src, dest)\n  return true\n}\n\nexport function apply(ctx: Context, config: Config) {\n  const serverDir = resolveUnderHome(config.serverDir, 'memory-vault-server')\n  const memoryPath = resolveUnderHome(config.memoryPath, 'memory-vault')\n\n  // Self-contained install: first boot copies the bundled server and vault\n  // starter under the harness home when they are missing. Env-overridden\n  // paths are respected (never overwritten, never copied over).\n  if (ensure(serverDir, join(packageRoot, 'server'), 'server.py')) {\n    console.log(`[memory-mcp] installed memory-vault-server -> ${serverDir}`)\n  }\n  if (ensure(memoryPath, join(packageRoot, 'vault'), 'type-registry.yaml')) {\n    console.log(`[memory-mcp] installed vault starter -> ${memoryPath}`)\n  }\n  // launcher.mjs runs the server via uv or the pip-venv fallback; upgrades of\n  // existing installs (server.py already present) still need the new files.\n  const bundled = join(packageRoot, 'server')\n  for (const file of ['launcher.mjs', 'requirements.txt']) {\n    if (ensureFile(serverDir, bundled, file)) {\n      console.log(`[memory-mcp] installed ${file} -> ${serverDir}`)\n    }\n  }\n  if (!existsSync(join(serverDir, 'server.py'))) {\n    console.warn(\n      `[memory-mcp] memory-vault-server not found at ${serverDir} and not bundled — ` +\n      'set DSH_MEMORY_SERVER_DIR (or run `node scripts/bundle-assets.mjs` in a checkout)',\n    )\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,OAAO;AAOpB,MAAaA,SAAyB,OAAO,OAAO;CAClD,YAAY,OAAO,QAAQ,CAAC,QAAQ,QAAQ,IAAI,mBAAmB,GAAG;CACtE,WAAW,OAAO,QAAQ,CAAC,QAAQ,QAAQ,IAAI,yBAAyB,GAAG;CAC5E,CAAC;AAEF,MAAM,cAAc,QAAQ,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,CAAC;;AAGpE,SAAS,UAAkB;CACzB,MAAM,MAAM,QAAQ,IAAI,UAAU,MAAM;AACxC,QAAO,OAAO,IAAI,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,OAAO;;;AAI9D,SAAS,iBAAiB,OAAe,SAAyB;CAChE,MAAM,IAAI,MAAM,MAAM;AACtB,KAAI,EAAE,WAAW,EAAG,QAAO,KAAK,SAAS,EAAE,QAAQ;AACnD,QAAO,WAAW,EAAE,GAAG,IAAI,KAAK,SAAS,EAAE,EAAE;;;AAI/C,SAAS,OAAO,QAAgB,SAAiB,KAAsB;AACrE,KAAI,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAE,QAAO;AAC1C,KAAI,CAAC,WAAW,QAAQ,CAAE,QAAO;AACjC,WAAU,QAAQ,EAAE,WAAW,MAAM,CAAC;AACtC,QAAO,SAAS,QAAQ,EAAE,WAAW,MAAM,CAAC;AAC5C,QAAO;;;AAIT,SAAS,WAAW,QAAgB,SAAiB,MAAuB;CAC1E,MAAM,OAAO,KAAK,QAAQ,KAAK;AAC/B,KAAI,WAAW,KAAK,CAAE,QAAO;CAC7B,MAAM,MAAM,KAAK,SAAS,KAAK;AAC/B,KAAI,CAAC,WAAW,IAAI,CAAE,QAAO;AAC7B,WAAU,QAAQ,EAAE,WAAW,MAAM,CAAC;AACtC,QAAO,KAAK,KAAK;AACjB,QAAO;;AAGT,SAAgB,MAAM,KAAc,QAAgB;CAClD,MAAM,YAAY,iBAAiB,OAAO,WAAW,sBAAsB;CAC3E,MAAM,aAAa,iBAAiB,OAAO,YAAY,eAAe;AAKtE,KAAI,OAAO,WAAW,KAAK,aAAa,SAAS,EAAE,YAAY,CAC7D,SAAQ,IAAI,iDAAiD,YAAY;AAE3E,KAAI,OAAO,YAAY,KAAK,aAAa,QAAQ,EAAE,qBAAqB,CACtE,SAAQ,IAAI,2CAA2C,aAAa;CAItE,MAAM,UAAU,KAAK,aAAa,SAAS;AAC3C,MAAK,MAAM,QAAQ,CAAC,gBAAgB,mBAAmB,CACrD,KAAI,WAAW,WAAW,SAAS,KAAK,CACtC,SAAQ,IAAI,0BAA0B,KAAK,MAAM,YAAY;AAGjE,KAAI,CAAC,WAAW,KAAK,WAAW,YAAY,CAAC,CAC3C,SAAQ,KACN,iDAAiD,UAAU,wGAE5D"}
+{"version":3,"file":"index.js","names":["parseYaml"],"sources":["../src/skills.ts","../src/index.ts"],"sourcesContent":["/**\n * Bundled skills shipped in this package: `brain` (read the vault) and\n * `checkpoint` (capture a session into it).\n *\n * A provider rather than `ctx.skills.register()` on purpose. A registration\n * lands at the runtime rank, which outranks a user's own skill directories,\n * while BUNDLED_SKILL_RANK is the weakest rank in the local discovery table:\n * shipping at the weakest rank means a user who drops their own `brain` into\n * `~/.agents/skills` keeps winning the name. These are defaults, not a takeover.\n *\n * Each SKILL.md stays the single source of its own name, description and\n * usage guidance — the frontmatter is parsed here with the same `yaml`\n * dependency the harness's own filesystem provider uses, so the exact file that\n * ships in this package also works copied into a user skill root.\n */\nimport { readFile } from 'node:fs/promises'\nimport { fileURLToPath } from 'node:url'\nimport { parse as parseYaml } from 'yaml'\nimport {\n  BUNDLED_SKILL_RANK,\n  type SkillCandidate,\n  type SkillDefinition,\n  type SkillProvider,\n  type SkillResourceBase,\n} from '@deepseek-ai/dsh-skill'\n\n/** Provider name registered on `ctx.skills`. */\nexport const SKILLS_PROVIDER = 'memory-mcp-skills'\n\n/** Shipped skill directories, relative to the package root. */\nconst SKILL_NAMES = ['brain', 'checkpoint'] as const\n\nconst SKILLS_ROOT = new URL('../skills/', import.meta.url)\nconst INVOCATION = { modelInvocable: true, userInvocable: true } as const\n\ninterface Frontmatter {\n  readonly name: string\n  readonly description: string\n  readonly whenToUse?: string\n}\n\nfunction skillUrl(name: string): URL {\n  return new URL(`${name}/SKILL.md`, SKILLS_ROOT)\n}\n\nfunction resourceBase(name: string): SkillResourceBase {\n  return { kind: 'directory', path: fileURLToPath(new URL(`${name}/`, SKILLS_ROOT)) }\n}\n\n/** Split YAML frontmatter from the body, mirroring the harness filesystem provider. */\nfunction splitFrontmatter(raw: string): { data: Record<string, unknown>; body: string } {\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n?/.exec(raw)\n  if (match === null) throw new Error('SKILL.md has no YAML frontmatter')\n  const parsed: unknown = parseYaml(match[1])\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    throw new TypeError('SKILL.md frontmatter must be a YAML mapping')\n  }\n  return { data: parsed as Record<string, unknown>, body: raw.slice(match[0].length).trim() }\n}\n\nfunction textField(data: Record<string, unknown>, key: string): string | undefined {\n  const value = data[key]\n  return typeof value === 'string' && value.length > 0 ? value : undefined\n}\n\n/** Read one shipped skill, rejecting a file whose frontmatter disagrees with its directory. */\nasync function loadSkill(name: string): Promise<{ frontmatter: Frontmatter; body: string }> {\n  const { data, body } = splitFrontmatter(await readFile(skillUrl(name), 'utf8'))\n  const declared = textField(data, 'name')\n  if (declared !== name) {\n    throw new Error(`skills/${name}/SKILL.md declares name \"${declared ?? '(none)'}\"`)\n  }\n  const description = textField(data, 'description')\n  if (description === undefined) throw new Error(`skills/${name}/SKILL.md has no description`)\n  const whenToUse = textField(data, 'whenToUse')\n  return {\n    frontmatter: { name, description, ...whenToUse === undefined ? {} : { whenToUse } },\n    body,\n  }\n}\n\n/** Skills shipped as packaged Markdown assets. */\nexport const skillsProvider: SkillProvider = {\n  name: SKILLS_PROVIDER,\n\n  async list(): Promise<readonly SkillCandidate[]> {\n    return await Promise.all(SKILL_NAMES.map(async (name) => {\n      const { frontmatter } = await loadSkill(name)\n      return {\n        ...frontmatter,\n        path: fileURLToPath(skillUrl(name)),\n        invocation: INVOCATION,\n        source: 'bundled',\n        provider: SKILLS_PROVIDER,\n        resourceBase: resourceBase(name),\n        rank: BUNDLED_SKILL_RANK,\n        locator: skillUrl(name),\n      }\n    }))\n  },\n\n  async get(candidate): Promise<SkillDefinition | undefined> {\n    // A body that is no longer loadable resolves to `undefined`: the registry\n    // passes that straight back to its caller, while throwing here would\n    // surface a raw ENOENT as a tool error instead of \"no longer available\".\n    const loaded = await loadSkill(candidate.name).catch(() => undefined)\n    if (loaded === undefined) return undefined\n    const { frontmatter, body } = loaded\n    return {\n      ...frontmatter,\n      path: fileURLToPath(skillUrl(candidate.name)),\n      invocation: INVOCATION,\n      source: 'bundled',\n      provider: SKILLS_PROVIDER,\n      resourceBase: resourceBase(candidate.name),\n      content: body,\n    }\n  },\n}\n","import { cpSync, existsSync, mkdirSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { dirname, isAbsolute, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { Context } from '@deepseek-ai/cordis'\nimport Schema from '@deepseek-ai/schemastery'\nimport { skillsProvider } from './skills.js'\n\nexport const name = 'memory-mcp'\n\nexport interface Config {\n  memoryPath: string\n  serverDir: string\n}\n\nexport const Config: Schema<Config> = Schema.object({\n  memoryPath: Schema.string().default(process.env.DSH_MEMORY_PATH ?? ''),\n  serverDir: Schema.string().default(process.env.DSH_MEMORY_SERVER_DIR ?? ''),\n})\n\nconst packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))\n\n/** Harness home, resolved like the harness itself ($DSH_HOME, or ~/.dsh). */\nfunction dshHome(): string {\n  const env = process.env.DSH_HOME?.trim()\n  return env && env.length > 0 ? env : join(homedir(), '.dsh')\n}\n\n/** Absolute paths stay; empty/relative values resolve under the harness home. */\nfunction resolveUnderHome(value: string, segment: string): string {\n  const v = value.trim()\n  if (v.length === 0) return join(dshHome(), segment)\n  return isAbsolute(v) ? v : join(dshHome(), v)\n}\n\n/** Copy the bundled dir into `target` when `key` is missing there. */\nfunction ensure(target: string, bundled: string, key: string): boolean {\n  if (existsSync(join(target, key))) return false\n  if (!existsSync(bundled)) return false\n  mkdirSync(target, { recursive: true })\n  cpSync(bundled, target, { recursive: true })\n  return true\n}\n\n/** Copy one bundled file into `target` when missing (upgrades add files 0.1.1 → 0.1.2). */\nfunction ensureFile(target: string, bundled: string, file: string): boolean {\n  const dest = join(target, file)\n  if (existsSync(dest)) return false\n  const src = join(bundled, file)\n  if (!existsSync(src)) return false\n  mkdirSync(target, { recursive: true })\n  cpSync(src, dest)\n  return true\n}\n\nexport function apply(ctx: Context, config: Config) {\n  // Ship the skills that drive the tools this plugin exposes, at the bundled\n  // rank, so a user's own `brain`/`checkpoint` in a skill directory still wins.\n  // Injected rather than declared in the plugin's `inject`: the vault bootstrap\n  // and the MCP client must keep working in a deployment with no skill catalog.\n  ctx.inject(['skills'], (ctx) => {\n    ctx.skills.registerProvider(() => skillsProvider)\n  })\n\n  const serverDir = resolveUnderHome(config.serverDir, 'memory-vault-server')\n  const memoryPath = resolveUnderHome(config.memoryPath, 'memory-vault')\n\n  // Self-contained install: first boot copies the bundled server and vault\n  // starter under the harness home when they are missing. Env-overridden\n  // paths are respected (never overwritten, never copied over).\n  if (ensure(serverDir, join(packageRoot, 'server'), 'server.py')) {\n    console.log(`[memory-mcp] installed memory-vault-server -> ${serverDir}`)\n  }\n  if (ensure(memoryPath, join(packageRoot, 'vault'), 'type-registry.yaml')) {\n    console.log(`[memory-mcp] installed vault starter -> ${memoryPath}`)\n  }\n  // launcher.mjs runs the server via uv or the pip-venv fallback; upgrades of\n  // existing installs (server.py already present) still need the new files.\n  const bundled = join(packageRoot, 'server')\n  for (const file of ['launcher.mjs', 'requirements.txt']) {\n    if (ensureFile(serverDir, bundled, file)) {\n      console.log(`[memory-mcp] installed ${file} -> ${serverDir}`)\n    }\n  }\n  if (!existsSync(join(serverDir, 'server.py'))) {\n    console.warn(\n      `[memory-mcp] memory-vault-server not found at ${serverDir} and not bundled — ` +\n      'set DSH_MEMORY_SERVER_DIR (or run `node scripts/bundle-assets.mjs` in a checkout)',\n    )\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luisarg/memory-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "DSH MCP client for the memory vault",
   "repository": {
@@ -19,6 +19,7 @@
     "dist/",
     "cordis.patch.yml",
     "server/",
+    "skills/",
     "vault/"
   ],
   "dsh": {
@@ -30,14 +31,21 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest run --passWithNoTests",
-    "prepare": "tsdown && node ../../scripts/bundle-assets.mjs"
+    "prepare": "tsdown",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/schemastery": "3.18.1"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "yaml": "^2.4.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0"
   },
   "devDependencies": {
-    "typescript": "^5.9.2",
-    "tsdown": "^0.15.6"
+    "@deepseek-ai/dsh-skill": "0.1.5-rc.2",
+    "typescript": "^7.0.2",
+    "tsdown": "^0.23.0",
+    "vitest": "^5.0.0"
   }
 }

package/server/server.py

@@ -1,8 +1,13 @@
 """MCP server exposing memory store tools via the Model Context Protocol.
 
-Eight tools (per openspec/specs/memory-mcp-server/spec.md):
+Ten tools (per openspec/specs/memory-mcp-server/spec.md):
     search_memory, store_decision, store_fact, store_learning,
-    store_convention, store_profile, export_memories, get_profile, ping.
+    store_convention, store_profile, store_source, export_memories,
+    get_profile, ping.
+
+Note: `type-registry.yaml` also declares `context` and `idea`. They are valid
+`entries.entry_type` values and legal filters here, but no `store_*` tool
+creates them — nothing writes them today.
 
 All reads are explicit (no background polling). Server validates storage
 accessibility at startup.
@@ -190,7 +195,13 @@ def _tool_definitions() -> list[Tool]:
     return [
         Tool(
             name="search_memory",
-            description="Search memory entries across projects. Omit project to search all projects.",
+            description=(
+                "Search memory entries across projects. Omit project to search all projects. "
+                "The query is tokenized and OR-matched (any term hits), ranked by relevance. "
+                "Tags are OR-matched too: passing ['ci','release'] returns entries with either tag. "
+                "Filters narrow the result set; at most 50 entries are returned. "
+                "Source entries are excluded unless entry_type='source' with no other filter."
+            ),
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -203,78 +214,143 @@ def _tool_definitions() -> list[Tool]:
         ),
         Tool(
             name="store_decision",
-            description="Store a decision entry",
+            description=(
+                "Store a decision: an architectural or design choice that was made and why. "
+                "Deduplicated by content hash, so re-storing the same text updates instead of "
+                "duplicating."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project", "content"],
                 "properties": {
                     "project": {"type": "string"},
-                    "content": {"type": "string"},
-                    "description": {"type": "string"},
-                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "content": {
+                        "type": "string",
+                        "description": "One paragraph, no headings or bullet lists.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "One-sentence queryable summary; derived from content if omitted.",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Lowercase-kebab tags, e.g. architecture/python/testing.",
+                    },
                     "openspec_change_id": {"type": "string"},
                 },
             },
         ),
         Tool(
             name="store_fact",
-            description="Store a fact entry",
+            description=(
+                "Store a fact: a stable, verifiable statement about the project (version, "
+                "constraint, path, endpoint). Deduplicated by content hash. Prefer one atomic "
+                "fact per call over a bundle of several."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project", "content"],
                 "properties": {
                     "project": {"type": "string"},
-                    "content": {"type": "string"},
-                    "description": {"type": "string"},
-                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "content": {
+                        "type": "string",
+                        "description": "One paragraph, no headings or bullet lists.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "One-sentence queryable summary; derived from content if omitted.",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Lowercase-kebab tags, e.g. architecture/python/testing.",
+                    },
                     "confidence": {"type": "number", "minimum": 0.0, "maximum": 1.0},
                 },
             },
         ),
         Tool(
             name="store_learning",
-            description="Store a learning entry",
+            description=(
+                "Store a learning: a non-obvious lesson, debugging insight, or solution found — "
+                "something that cost effort and would otherwise be rediscovered. Deduplicated by "
+                "content hash."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project", "content"],
                 "properties": {
                     "project": {"type": "string"},
-                    "content": {"type": "string"},
-                    "description": {"type": "string"},
-                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "content": {
+                        "type": "string",
+                        "description": "One paragraph, no headings or bullet lists.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "One-sentence queryable summary; derived from content if omitted.",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Lowercase-kebab tags, e.g. architecture/python/testing.",
+                    },
                 },
             },
         ),
         Tool(
             name="store_convention",
-            description="Store a convention entry",
+            description=(
+                "Store a convention: an agreed style rule, naming pattern, or coding standard. "
+                "Deduplicated by content hash."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project", "content"],
                 "properties": {
                     "project": {"type": "string"},
-                    "content": {"type": "string"},
-                    "description": {"type": "string"},
-                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "content": {
+                        "type": "string",
+                        "description": "One paragraph, no headings or bullet lists.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "One-sentence queryable summary; derived from content if omitted.",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Lowercase-kebab tags, e.g. architecture/python/testing.",
+                    },
                 },
             },
         ),
         Tool(
             name="store_profile",
-            description="Store or update a user profile entry for a project",
+            description=(
+                "Replace the tech profile for a project. One profile per project: the content "
+                "overwrites the previous one, it does not append. Pass the complete profile text."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project", "content"],
                 "properties": {
                     "project": {"type": "string"},
-                    "content": {"type": "string"},
+                    "content": {
+                        "type": "string",
+                        "description": "The full profile — replaces the stored one.",
+                    },
                     "tags": {"type": "array", "items": {"type": "string"}},
                 },
             },
         ),
         Tool(
             name="store_source",
-            description="Store a source reference (article, transcript, PDF, video, link)",
+            description=(
+                "Store an external source reference (article, transcript, PDF, video, link) under "
+                "raw/. Immutable: a later store with the same URL returns the existing entry, and "
+                "reusing a title slug with different content is rejected."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["url", "title", "description", "source_kind"],
@@ -294,7 +370,10 @@ def _tool_definitions() -> list[Tool]:
         ),
         Tool(
             name="export_memories",
-            description="Export all memory entries for a project (no limit)",
+            description=(
+                "Export every stored entry for one project, newest first, with no result limit. "
+                "Use for a full project dump, not for lookups — search_memory is cheaper."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project"],
@@ -306,7 +385,11 @@ def _tool_definitions() -> list[Tool]:
         ),
         Tool(
             name="get_profile",
-            description="Retrieve the global tech profile for a project",
+            description=(
+                "Retrieve the stored tech profile for a project. Returns profile entries by "
+                "default; pass entry_type to query another type instead (then it is a "
+                "most-recent-first lookup capped at 10)."
+            ),
             inputSchema={
                 "type": "object",
                 "required": ["project"],

package/server/store.py

@@ -770,12 +770,15 @@ class MemoryStore:
         project: str,
         entry_type: str | None = None,
     ) -> list[dict]:
-        """Retrieve profile entries for a project."""
-        sql = "SELECT * FROM entries WHERE project = ?"
-        params: list = [project]
-        if entry_type:
-            sql += " AND entry_type = ?"
-            params.append(entry_type)
+        """Retrieve the profile for a project.
+
+        Defaults to ``profile`` entries: the tool is named get_profile, so an
+        unfiltered call returning the 10 most recent rows of any type was a
+        silent wrong answer. Pass ``entry_type`` to use it as a recency query.
+        """
+        entry_type = entry_type or "profile"
+        sql = "SELECT * FROM entries WHERE project = ? AND entry_type = ?"
+        params: list = [project, entry_type]
         sql += " ORDER BY updated_at DESC LIMIT 10"
         rows = self.db.execute(sql, params).fetchall()
         return [dict(r) for r in rows]

package/server/test_get_profile.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Self-check: get_profile answers with the profile, not with recent noise.
+
+Regression guard for the bug where an unfiltered get_profile returned the 10
+most recently updated rows of ANY type, so a caller asking for the profile of a
+busy project got unrelated decisions and facts.
+
+Run: python3 memory-vault-server/test_get_profile.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+SERVER_DIR = Path(__file__).resolve().parent
+REPO_VAULT = SERVER_DIR.parent / "memory-vault"
+sys.path.insert(0, str(SERVER_DIR))
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        # store.py resolves the type registry from MEMORY_PATH at import time,
+        # so seed the throwaway vault before importing it.
+        vault = Path(tmp)
+        (vault / "projects").mkdir()
+        shutil.copy(REPO_VAULT / "type-registry.yaml", vault / "type-registry.yaml")
+        os.environ["MEMORY_PATH"] = str(vault)
+        import store as store_mod
+
+        s = store_mod.MemoryStore(storage_path=vault)
+        s.initialize()
+
+        s.upsert_profile(project="proj", content="PROFILE: python + sqlite")
+        # Written afterwards, so these outrank the profile in updated_at:
+        # the old code returned them and called it a profile.
+        s.upsert_entry("decision", "proj", "DECISION: use sqlite for storage")
+        s.upsert_entry("fact", "proj", "FACT: python 3.11 is required")
+
+        got = s.get_profile(project="proj")
+        assert len(got) == 1, f"expected only the profile row, got {len(got)}: {got}"
+        assert got[0]["entry_type"] == "profile", got[0]["entry_type"]
+        assert "PROFILE" in got[0]["content"], got[0]["content"]
+
+        # entry_type=None must behave exactly like the default.
+        assert s.get_profile(project="proj", entry_type=None) == got
+
+        # Explicit entry_type still works (and is now a plain recency lookup).
+        facts = s.get_profile(project="proj", entry_type="fact")
+        assert len(facts) == 1 and facts[0]["entry_type"] == "fact", facts
+
+        # A project with no profile yields nothing rather than unrelated rows.
+        s.upsert_entry("fact", "other", "FACT: unrelated project")
+        assert s.get_profile(project="other") == [], "profile leaked across projects"
+
+        # The MCP tool handler agrees (binds the tool default to the store fix).
+        # Needs the pinned `mcp` version from requirements.txt; skip when the
+        # ambient one is older instead of failing the whole check.
+        try:
+            import server
+
+            found = json.loads(server.handle_get_profile(s, {"project": "proj"}))
+            assert len(found) == 1 and found[0]["entry_type"] == "profile", found
+        except ImportError as exc:
+            print(f"skip: MCP handler assertion ({exc})")
+
+        s._db.close()
+
+    print("ok: get_profile returns the profile, not the most recent rows")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/brain/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: brain
+description: >-
+  Read what the memory vault already knows: topic search, recall by project, the user
+  profile, and full project dumps, through the memory plugin's MCP tools. Use when the
+  user invokes /brain, asks "what do you know about", "search your memory", "recall what
+  we said about", "do you remember when", "bring up the profile", or needs prior-session
+  context before acting.
+whenToUse: "/brain <query> · /brain profile · /brain export <project>"
+---
+
+# Brain — read from the vault
+
+The memory plugin exposes a Markdown knowledge base (OKF) over MCP; the vault's
+`memory.db` is a derived SQLite FTS5 index over that Markdown. Read it through the
+plugin's tools — `mcp__memory__*` when the server is named `memory` — never by hand.
+
+**`/brain` is read-only.** It writes nothing: capture is `/checkpoint`, and the profile
+layer is `/checkpoint-perfil`.
+
+## 1. Locate the vault
+
+Only needed when you touch the filesystem. The plugin resolves the vault in this order:
+`DSH_MEMORY_PATH` → `$DSH_HOME/memory-vault` (`~/.dsh/memory-vault` when `DSH_HOME` is
+unset) → the profile's own patch. The server receives the result as `MEMORY_PATH`. Paths
+are absolute and do not depend on the cwd.
+
+## 2. Resolve the project
+
+`project` is the folder key under `<vault>/projects/`. A misspelled name silently creates
+a new project — there is no validation against a list — so list before filtering:
+
+```sh
+ls "${DSH_MEMORY_PATH:-${DSH_HOME:-$HOME/.dsh}/memory-vault}"/projects/
+```
+
+The key is **not necessarily the repo basename**: it can be the `package.json` name, a
+curated human name, or a nested path (`<org>/<repo>`). When unsure, search **without**
+`project` (that scans every project) and narrow afterwards.
+
+## 3. Pick the tool
+
+| Need | Tool | Note |
+|---|---|---|
+| A topic, a decision, a bug, "what do you know about X" | `search_memory` | `query` is tokenized and **OR**-matched, ranked by relevance — not an exact phrase |
+| Who the user is, the profile, the stack | `get_profile` | profile entries for one project |
+| Everything about one project | `export_memories` | no limit; for dumps, not lookups |
+| Is the server reachable? | `ping` | health check |
+
+Traps that cost real time:
+
+- **`search_memory` with `entry_type=profile` always returns 0 results.** Profiles come
+  from `get_profile`.
+- `get_profile` with **any other** `entry_type` does not filter: it returns the 10 most
+  recent entries of that type.
+- `tags` is **OR** as well: `["ci","release"]` returns entries carrying *either* tag.
+- `search_memory` returns **at most 50** entries. For a whole project, use
+  `export_memories`.
+- `source` entries are excluded from every filtered search: only `entry_type="source"`
+  with no other filter returns them.
+
+## 4. Profile layers are documents, not index entries
+
+A vault may keep a profile layer: a `profile/` directory inside a project, usually a
+`README.md` map plus numbered documents. Those files are **not** in `memory.db`, so
+`search_memory` never returns them — read them from the filesystem. `get_profile` returns
+something else: internal metadata rows that live only in SQLite and write no Markdown, so
+an index rebuild from Markdown cannot recover them.
+
+## 5. Answer
+
+- Cite project + entry (its description or first line). Quote; do not paraphrase a claim
+  into something stronger than it is.
+- Never fill gaps: if the vault does not say it, it is not there.
+- No results? Say so, and separate **"not in the vault"** from **"I searched badly"**:
+  retry without `project`, with other tags, or with `export_memories`.

package/skills/checkpoint/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: checkpoint
+description: >-
+  Capture what a session produced into the memory vault as decision, fact, learning and
+  convention entries through the memory plugin's tools, then commit the vault. Use when
+  the user invokes /checkpoint, says "save this session", "run the checkpoint", "remember
+  this", or when a memory-auto [memory-checkpoint] prompt arrives.
+whenToUse: "/checkpoint [topic] — with no argument it reviews the whole session"
+---
+
+# Checkpoint — capture the session
+
+Write into the vault through the memory plugin's tools (`mcp__memory__*` when the server
+is named `memory`). Never edit `memory.db` or the entry Markdown by hand: the tools keep
+the Markdown source and the derived index in sync.
+
+The `memory-auto` plugin runs this **same** procedure automatically — that is what its
+`[memory-checkpoint]` prompt asks for: same types, same selection rules. If the request
+arrived as `[memory-checkpoint]`, this is the path. Do not write the same thing twice:
+search first (step 3).
+
+## 1. Resolve the project
+
+`project` is the folder key under `<vault>/projects/`; a misspelled name silently creates a
+new project:
+
+```sh
+ls "${DSH_MEMORY_PATH:-${DSH_HOME:-$HOME/.dsh}/memory-vault}"/projects/
+```
+
+It is not always the repo basename — it can be the `package.json` name, a curated name, or
+a nested path (`<org>/<repo>`). Reuse the key the vault already uses for this work.
+
+## 2. Decide what qualifies
+
+| Type | Tool | What goes in |
+|---|---|---|
+| **decision** | `store_decision` | Architecture or design choices, **and why**. Pass `openspec_change_id` when the choice came from a change |
+| **fact** | `store_fact` | Stable, verifiable statements: versions, constraints, paths, endpoints. `confidence` 0.0–1.0 |
+| **learning** | `store_learning` | Non-obvious lessons, debugging insights, a solution that cost effort |
+| **convention** | `store_convention` | Agreed style rules, naming patterns, standards |
+| **source** | `store_source` | External references (article, transcript, PDF, video, link), stored under `raw/`. Immutable per URL |
+
+**Do not store:** greetings, acknowledgements, restatements of the request, or anything you
+cannot ground in this session. Few high-signal entries beat many weak ones. If nothing
+qualifies, say so and write nothing — an empty checkpoint is a valid outcome.
+
+## 3. Search before writing
+
+`search_memory` on the topic first. Deduplication is a hash of
+`(project, entry_type, content)` over normalized content: resending the same text with
+different casing **updates** the existing entry; changing one word creates a **new** one.
+
+## 4. Write
+
+- `content`: **one paragraph** — no headings, no lists, no markdown structure.
+- `tags`: lowercase-kebab, at least one (`architecture`, `python`, `testing`, `ci`…).
+- `confidence` only has an effect on `store_fact`; the other tools accept and ignore it.
+- `store_profile` is **not** used here: it replaces a project's whole profile entry (one
+  per project, no Markdown written). The profile layer has its own procedure.
+
+## 5. Close
+
+The vault is its own git repository — commit it:
+
+```sh
+cd "${DSH_MEMORY_PATH:-${DSH_HOME:-$HOME/.dsh}/memory-vault}"
+git add -A && git commit -m "memory(<project>): <what changed and why>"
+```
+
+Follow whatever commit convention the vault's own history uses, and do not push unless
+asked: with no remote configured, the commit is the end of the line.
+
+Report 5–10 lines: what was written (tool + description), what was left out and why, and
+what could not be verified.