@luisarg/memory-mcp 0.1.4 → 0.1.6

package/README.md

@@ -14,18 +14,38 @@ vault's tools (`search_memory`, `store_*`, `export_memories`, `get_profile`,
 dsh plugin --profile web add @luisarg/memory-mcp
 ```
 
-Requires `uv` on PATH — the plugin spawns the server with `uv run`.
+`uv` on PATH is recommended but not required: the bundled `launcher.mjs` runs the server with
+`uv run` when uv is present and falls back to a pip-managed venv (`python3 -m venv` +
+`pip install -r requirements.txt`, network on first boot) when it is not.
+
+## Skills
+
+The package also ships the two skills that drive its tools, so installing it is enough to get the
+commands — nothing has to be copied into a skill directory:
+
+| Command | Source | What it does |
+|---|---|---|
+| `/brain` | `skills/brain/SKILL.md` | Reads the vault: topic search, recall by project, the profile, full exports — including the tool traps (`entry_type=profile` in `search_memory` always returns 0; `tags` are OR-matched; searches cap at 50) |
+| `/checkpoint` | `skills/checkpoint/SKILL.md` | Captures the session as `decision`/`fact`/`learning`/`convention` entries, then commits the vault |
+
+They register at DSH's **bundled** rank (600), the weakest in the local discovery table, so a
+skill of the same name in a user or project root still wins. Each `SKILL.md` is the single source
+of its own name, description and usage guidance: the provider parses its frontmatter with `yaml`,
+so the same file also works copied into `~/.agents/skills`. Registration goes through
+`ctx.inject(['skills'], …)`, so a deployment with no skill catalog still gets the vault
+bootstrap and the MCP client.
 
 ## Configuration
 
 | Variable | Purpose | Default |
 |---|---|---|
 | `DSH_MEMORY_SERVER_DIR` | directory containing `server.py` | `$DSH_HOME/memory-vault-server` |
-| `DSH_MEMORY_PATH` | vault directory (forwarded to the server as `MEMORY_PATH`) | `$DSH_HOME/memory-vault` |
+| `DSH_MEMORY_PATH` | vault directory (forwarded to the server as `MEMORY_PATH`) | `~/.memories` |
 
 The bundle ships no cwd-dependent paths: the `cordis.patch.yml` layer resolves both
-values from the environment, falling back to the harness home (`$DSH_HOME`, or
-`~/.dsh`) — DSH does not chdir, so launching from any directory works.
+values from the environment. The vault falls back to the OS home (`~/.memories`, which
+`DSH_HOME` does not move); the server to the harness home (`$DSH_HOME`, or `~/.dsh`) —
+DSH does not chdir, so launching from any directory works.
 
 ## Development
 

package/cordis.patch.yml

@@ -1,7 +1,8 @@
 # bundle @luisarg/memory-mcp — MCP stdio wrapper for memory-vault
 # overrides vía env: DSH_MEMORY_PATH, DSH_MEMORY_SERVER_DIR
-# defaults resuelven bajo el home del harness (cwd-independent):
-#   $DSH_HOME/memory-vault-server y $DSH_HOME/memory-vault (~/.dsh por defecto)
+# cwd-independent:
+#   vault  -> ~/.memories (OS home, ignores DSH_HOME)
+#   server -> $DSH_HOME/memory-vault-server (~/.dsh por defecto)
 - insert:
     - id: memory-mcp-bootstrap
       name: '@luisarg/memory-mcp'
@@ -15,6 +16,6 @@
         command: !!js process.execPath
         args: [!!js "(process.env.DSH_MEMORY_SERVER_DIR ?? dshHomePath('memory-vault-server')) + '/launcher.mjs'"]
         env:
-          MEMORY_PATH: !!js process.env.DSH_MEMORY_PATH ?? dshHomePath('memory-vault')
+          MEMORY_PATH: !!js process.env.DSH_MEMORY_PATH ?? (process.env.HOME || process.env.USERPROFILE || '') + '/.memories'
           UV_CACHE_DIR: /tmp/uv-cache
         cwd: !!js process.env.DSH_MEMORY_SERVER_DIR ?? dshHomePath('memory-vault-server')

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;qBAOa;iBAEI;EACf;EACA;;qBAGW,QAAQ,OAAO;wBAwCZ,MAAM,KAAK,SAAS,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;qBAQa;iBAEI;EACf;EACA;;qBAGW,QAAQ,OAAO;wBA+CZ,MAAM,KAAK,SAAS,QAAQ"}

package/dist/index.js

@@ -3,6 +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({
@@ -21,6 +124,12 @@ function resolveUnderHome(value, segment) {
 	if (v.length === 0) return join(dshHome(), segment);
 	return isAbsolute(v) ? v : join(dshHome(), v);
 }
+/** Vault root: `~/.memories` by default, independent of `$DSH_HOME`. */
+function resolveMemoryPath(value) {
+	const v = value.trim();
+	if (v.length === 0) return join(homedir(), ".memories");
+	return isAbsolute(v) ? v : join(homedir(), v);
+}
 /** Copy the bundled dir into `target` when `key` is missing there. */
 function ensure(target, bundled, key) {
 	if (existsSync(join(target, key))) return false;
@@ -40,8 +149,11 @@ 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");
+	const memoryPath = resolveMemoryPath(config.memoryPath);
 	if (ensure(serverDir, join(packageRoot, "server"), "server.py")) console.log(`[memory-mcp] installed memory-vault-server -> ${serverDir}`);
 	if (ensure(memoryPath, join(packageRoot, "vault"), "type-registry.yaml")) console.log(`[memory-mcp] installed vault starter -> ${memoryPath}`);
 	const bundled = join(packageRoot, "server");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"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,MAAa,SAAyB,OAAO,OAAO;CAClD,YAAY,OAAO,OAAO,CAAC,CAAC,QAAQ,QAAQ,IAAI,mBAAmB,EAAE;CACrE,WAAW,OAAO,OAAO,CAAC,CAAC,QAAQ,QAAQ,IAAI,yBAAyB,EAAE;AAC5E,CAAC;AAED,MAAM,cAAc,QAAQ,QAAQ,cAAc,YAAY,GAAG,CAAC,CAAC;;AAGnE,SAAS,UAAkB;CACzB,MAAM,MAAM,QAAQ,IAAI,UAAU,KAAK;CACvC,OAAO,OAAO,IAAI,SAAS,IAAI,MAAM,KAAK,QAAQ,GAAG,MAAM;AAC7D;;AAGA,SAAS,iBAAiB,OAAe,SAAyB;CAChE,MAAM,IAAI,MAAM,KAAK;CACrB,IAAI,EAAE,WAAW,GAAG,OAAO,KAAK,QAAQ,GAAG,OAAO;CAClD,OAAO,WAAW,CAAC,IAAI,IAAI,KAAK,QAAQ,GAAG,CAAC;AAC9C;;AAGA,SAAS,OAAO,QAAgB,SAAiB,KAAsB;CACrE,IAAI,WAAW,KAAK,QAAQ,GAAG,CAAC,GAAG,OAAO;CAC1C,IAAI,CAAC,WAAW,OAAO,GAAG,OAAO;CACjC,UAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;CACrC,OAAO,SAAS,QAAQ,EAAE,WAAW,KAAK,CAAC;CAC3C,OAAO;AACT;;AAGA,SAAS,WAAW,QAAgB,SAAiB,MAAuB;CAC1E,MAAM,OAAO,KAAK,QAAQ,IAAI;CAC9B,IAAI,WAAW,IAAI,GAAG,OAAO;CAC7B,MAAM,MAAM,KAAK,SAAS,IAAI;CAC9B,IAAI,CAAC,WAAW,GAAG,GAAG,OAAO;CAC7B,UAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;CACrC,OAAO,KAAK,IAAI;CAChB,OAAO;AACT;AAEA,SAAgB,MAAM,KAAc,QAAgB;CAClD,MAAM,YAAY,iBAAiB,OAAO,WAAW,qBAAqB;CAC1E,MAAM,aAAa,iBAAiB,OAAO,YAAY,cAAc;CAKrE,IAAI,OAAO,WAAW,KAAK,aAAa,QAAQ,GAAG,WAAW,GAC5D,QAAQ,IAAI,iDAAiD,WAAW;CAE1E,IAAI,OAAO,YAAY,KAAK,aAAa,OAAO,GAAG,oBAAoB,GACrE,QAAQ,IAAI,2CAA2C,YAAY;CAIrE,MAAM,UAAU,KAAK,aAAa,QAAQ;CAC1C,KAAK,MAAM,QAAQ,CAAC,gBAAgB,kBAAkB,GACpD,IAAI,WAAW,WAAW,SAAS,IAAI,GACrC,QAAQ,IAAI,0BAA0B,KAAK,MAAM,WAAW;CAGhE,IAAI,CAAC,WAAW,KAAK,WAAW,WAAW,CAAC,GAC1C,QAAQ,KACN,iDAAiD,UAAU,uGAE7D;AAEJ"}
+{"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/** Vault root: `~/.memories` by default, independent of `$DSH_HOME`. */\nfunction resolveMemoryPath(value: string): string {\n  const v = value.trim()\n  if (v.length === 0) return join(homedir(), '.memories')\n  return isAbsolute(v) ? v : join(homedir(), 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 = resolveMemoryPath(config.memoryPath)\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.4",
+  "version": "0.1.6",
   "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"
+    "prepare": "tsdown",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/schemastery": "3.18.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": {
+    "@deepseek-ai/dsh-skill": "0.1.5-rc.2",
     "typescript": "^7.0.2",
-    "tsdown": "^0.23.0"
+    "tsdown": "^0.23.0",
+    "vitest": "^5.0.0"
   }
 }

package/server/cli.py

@@ -8,10 +8,17 @@ from pathlib import Path
 
 
 def get_memory_path() -> Path:
-    """Return MEMORY_PATH from env, or default to `<project>/memory-vault/`."""
+    """Vault root: `$MEMORY_PATH`, else `~/.memories`, else this checkout's starter.
+
+    The last fallback keeps a bare `python server.py` (CI smoke test, dev) working
+    before any vault exists at the default location.
+    """
     env = os.environ.get("MEMORY_PATH")
     if env:
         return Path(env)
+    home_vault = Path.home() / ".memories"
+    if (home_vault / "type-registry.yaml").is_file():
+        return home_vault
     return Path(__file__).resolve().parent.parent / "memory-vault"
 
 

package/server/rebuild_index.py

@@ -160,7 +160,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "--memory-path",
         default=None,
-        help="OKF bundle directory (default: $MEMORY_PATH or repo memory-vault)",
+        help="OKF bundle directory (default: $MEMORY_PATH, else ~/.memories)",
     )
     args = parser.parse_args(argv)
 
@@ -169,8 +169,9 @@ def main(argv: list[str] | None = None) -> int:
     if args.memory_path:
         os.environ["MEMORY_PATH"] = str(Path(args.memory_path).resolve())
     import store as _store_mod
+    from cli import get_memory_path
 
-    memory_path = Path(os.environ.get("MEMORY_PATH", "")).resolve()
+    memory_path = get_memory_path().resolve()
     if not memory_path.is_dir():
         print(f"error: {memory_path} is not a directory", file=sys.stderr)
         return 2

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` → `$HOME/.memories` (the OS home — `DSH_HOME` does not move it) → 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:-$HOME/.memories}"/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:-$HOME/.memories}"/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:-$HOME/.memories}"
+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.