pi-claude-store 0.1.1 → 0.1.3

package/README.md

@@ -68,12 +68,6 @@ by the directory itself.
 pi install npm:pi-claude-store
 ```
 
-Or track `main` (maintainers/development — updates with every merge):
-
-```bash
-pi install git:github.com/yg-codes/pi-claude-store
-```
-
 ## Development
 
 ```bash

package/extensions/claude-store/index.ts

@@ -60,7 +60,8 @@ export default function (pi: ExtensionAPI) {
 		label: "Read memory",
 		description:
 			"Read one memory from the store shared with Claude Code. Takes the memory name — " +
-			"the filename without the .md extension, as listed in the injected memory index.",
+			"the filename without the .md extension. memory_list shows the file stem in " +
+			"parentheses when it differs from the frontmatter name.",
 		promptSnippet: "Read a stored memory by name",
 		promptGuidelines: [
 			"Call memory_read when an entry in the memory index looks relevant to the current task.",
@@ -73,7 +74,9 @@ export default function (pi: ExtensionAPI) {
 			try {
 				const memory = readMemory(dir, params.name);
 				if (!memory) {
-					const known = listMemories(dir).map((m) => m.name);
+					const known = listMemories(dir).map((m) =>
+						m.name && m.name !== m.file ? `${m.file ?? m.name} (name: ${m.name})` : (m.file ?? m.name),
+					);
 					return {
 						content: [
 							{
@@ -307,7 +310,13 @@ export default function (pi: ExtensionAPI) {
 					{
 						type: "text" as const,
 						text: memories.length
-							? memories.map((m) => `- ${m.name} — ${m.description}`).join("\n")
+							? memories
+								.map((m) =>
+									m.name && m.name !== m.file
+										? `- ${m.file ?? m.name} (name: ${m.name}) — ${m.description}`
+										: `- ${m.file ?? m.name} — ${m.description}`,
+								)
+								.join("\n")
 							: "No memories stored for this project.",
 					},
 				],

package/extensions/claude-store/memory-core.ts

@@ -16,6 +16,19 @@
  *
  * Pure functions plus thin fs wrappers — no pi imports, so it is testable
  * with plain `node --test`.
+ *
+ * 2026-10-10 caveat fixes (each pinned by a "(caveat)" test):
+ * - Memories are addressable by file stem OR frontmatter `name:` — the real
+ *   store has files where the two differ (underscore stems vs hyphen names,
+ *   `feedback_`-prefixed stems, names with spaces), and read/delete by the
+ *   advertised name used to fail while the error's "Available" list showed
+ *   that very name.
+ * - Index pointer lines may carry a marker emoji before the bracket
+ *   (`- 🔴 [T](a.md) — hook`); parse/render/upsert/remove keep the marker, so
+ *   writes no longer leave stale duplicate lines and deletes no longer orphan
+ *   them.
+ * - Updates preserve unknown frontmatter fields (originSessionId, …) and bump
+ *   `metadata.modified` instead of flattening the block to a fixed shape.
  */
 
 import fs from "node:fs";
@@ -28,6 +41,8 @@ export interface IndexEntry {
 	title: string;
 	file: string;
 	hook: string;
+	/** Marker before the bracket (`🔴` in `- 🔴 [T](a.md) — h`); absent on plain lines. */
+	marker?: string;
 }
 
 export interface Memory {
@@ -35,6 +50,8 @@ export interface Memory {
 	description: string;
 	type: string;
 	body: string;
+	/** File stem (filename without .md) — the name memory_read resolves first. */
+	file?: string;
 }
 
 export interface WriteMemoryInput {
@@ -66,17 +83,29 @@ export function memoryDirFor(cwd: string): string {
 	return path.join(os.homedir(), ".claude", "projects", sanitizePath(root), "memory");
 }
 
-/** Parse `- [Title](file.md) — hook` pointer lines, ignoring anything else. */
+/**
+ * Parse `- [Title](file.md) — hook` pointer lines, ignoring anything else.
+ * A short marker of non-word symbols may sit between the dash and the
+ * bracket (`- 🔴 [T](a.md) — hook`); it is captured and preserved. Prose
+ * bullets whose prefix contains word characters (`- See the [x](y.md)`) are
+ * still ignored.
+ */
+const INDEX_LINE_RE =
+	/^\s*-\s*([^\w\s()[\]]{1,4})?\s*\[([^\]]*)\]\(([^)]+)\)\s*(?:—\s*(.*))?$/;
+
 export function parseIndex(md: string): IndexEntry[] {
 	const entries: IndexEntry[] = [];
 	for (const line of md.split("\n")) {
-		const match = /^\s*-\s*\[([^\]]*)\]\(([^)]+)\)\s*(?:—\s*(.*))?$/.exec(line);
+		const match = INDEX_LINE_RE.exec(line);
 		if (!match) continue;
-		entries.push({
-			title: match[1].trim(),
-			file: match[2].trim(),
-			hook: (match[3] ?? "").trim(),
-		});
+		const marker = match[1]?.trim();
+		const entry: IndexEntry = {
+			title: match[2].trim(),
+			file: match[3].trim(),
+			hook: (match[4] ?? "").trim(),
+		};
+		if (marker) entry.marker = marker;
+		entries.push(entry);
 	}
 	return entries;
 }
@@ -95,35 +124,132 @@ function sanitizeInline(value: string): string {
 function renderIndexLine(entry: IndexEntry): string {
 	// Square brackets are stripped from the title: a `]` would end the link
 	// text early and let title content capture the file field on re-parse,
-	// forging an index entry that points at an attacker-chosen name. Brackets
-	// in the hook are inert — everything after the em dash is captured as hook
-	// text and cannot restructure the parse.
-	const title = sanitizeInline(entry.title).replace(/[\[\]]/g, "");
+	// forging an index entry that points at an attacker-chosen name. The
+	// marker is stripped of brackets and parens for the same reason; hook
+	// content after the em dash cannot restructure the parse.
+	const marker = sanitizeInline(entry.marker ?? "").replace(/[[\]()]/g, "");
+	const title = sanitizeInline(entry.title).replace(/[[\]]/g, "");
 	const hook = sanitizeInline(entry.hook);
 	const file = sanitizeInline(entry.file);
-	return hook ? `- [${title}](${file}) — ${hook}` : `- [${title}](${file})`;
+	const lead = marker ? `- ${marker} ` : "- ";
+	return hook ? `${lead}[${title}](${file}) — ${hook}` : `${lead}[${title}](${file})`;
 }
 
-/** Replace the pointer line for `entry.file` if present, otherwise append it. */
+/**
+ * Replace the pointer line for `entry.file` if present, otherwise append it.
+ * The first matching line is rewritten (keeping its existing marker when the
+ * entry carries none); further duplicates for the same file are dropped —
+ * one pointer line per memory, per the store's own hygiene convention.
+ */
 export function upsertIndexLine(md: string, entry: IndexEntry): string {
-	const rendered = renderIndexLine(entry);
 	const lines = md.split("\n");
 	while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
 
 	let replaced = false;
-	const next = lines.map((line) => {
+	const next: string[] = [];
+	for (const line of lines) {
 		const parsed = parseIndex(line)[0];
 		if (parsed && parsed.file === entry.file) {
-			replaced = true;
-			return rendered;
+			if (!replaced) {
+				next.push(renderIndexLine(entry.marker ? entry : { ...entry, marker: parsed.marker }));
+				replaced = true;
+			}
+			continue; // duplicate pointer line for the same file — collapse it
 		}
-		return line;
-	});
+		next.push(line);
+	}
 
-	if (!replaced) next.push(rendered);
+	if (!replaced) next.push(renderIndexLine(entry));
 	return `${next.join("\n")}\n`;
 }
 
+interface MemoryFile {
+	/** Filename (basename, with .md). */
+	fileName: string;
+	/** Filename without .md — the canonical address for reads. */
+	stem: string;
+	filePath: string;
+	memory: Memory;
+}
+
+/** All memory files in the directory (sorted, no symlinks, no MEMORY.md). */
+function listMemoryFiles(dir: string): MemoryFile[] {
+	if (!fs.existsSync(dir)) return [];
+	return fs
+		.readdirSync(dir)
+		.filter((file) => file.endsWith(".md") && file !== INDEX_FILE)
+		.filter((file) => {
+			try {
+				return !fs.lstatSync(path.join(dir, file)).isSymbolicLink();
+			} catch {
+				return false;
+			}
+		})
+		.sort()
+		.map((file) => {
+			const filePath = path.join(dir, file);
+			const stem = path.basename(file, ".md");
+			const parsed = parseMemory(fs.readFileSync(filePath, "utf8"));
+			return {
+				fileName: file,
+				stem,
+				filePath,
+				memory: { ...parsed, name: parsed.name || stem, file: stem },
+			};
+		});
+}
+
+/**
+ * Split a memory file into its raw frontmatter lines (null when absent or
+ * the closing delimiter sits beyond the 30-line window) and its body.
+ */
+function splitFrontmatter(text: string): { frontmatter: string[] | null; body: string } {
+	const lines = text.split(/\r?\n/);
+	if (lines[0] !== "---") return { frontmatter: null, body: text.trim() };
+	const limit = Math.min(lines.length, FRONTMATTER_MAX_LINES);
+	for (let i = 1; i < limit; i++) {
+		if (lines[i] === "---") {
+			return {
+				frontmatter: lines.slice(1, i),
+				body: lines
+					.slice(i + 1)
+					.join("\n")
+					.replace(/^\s*\n/, "")
+					.trimEnd(),
+			};
+		}
+	}
+	return { frontmatter: null, body: text.trim() };
+}
+
+function setTopLevelKey(fm: string[], key: string, value: string): void {
+	const re = new RegExp(`^${key}:`);
+	const idx = fm.findIndex((line) => re.test(line));
+	if (idx >= 0) fm[idx] = `${key}: ${value}`;
+	else fm.push(`${key}: ${value}`);
+}
+
+/** Set `key` inside the indented block introduced by `block:`; insert the key when absent. */
+function setNestedKey(fm: string[], block: string, key: string, value: string): void {
+	const blockRe = new RegExp(`^${block}:\\s*$`);
+	const blockIdx = fm.findIndex((line) => blockRe.test(line));
+	if (blockIdx === -1) {
+		fm.push(`${block}:`);
+		fm.push(`  ${key}: ${value}`);
+		return;
+	}
+	let end = blockIdx + 1;
+	while (end < fm.length && /^\s+/.test(fm[end] ?? "")) end++;
+	const keyRe = new RegExp(`^\\s+${key}:`);
+	for (let i = blockIdx + 1; i < end; i++) {
+		if (keyRe.test(fm[i] ?? "")) {
+			fm[i] = `  ${key}: ${value}`;
+			return;
+		}
+	}
+	fm.splice(end, 0, `  ${key}: ${value}`);
+}
+
 /**
  * Split a memory file into its frontmatter fields and body.
  *
@@ -132,38 +258,29 @@ export function upsertIndexLine(md: string, entry: IndexEntry): string {
  * Claude Code's rule. A body that happens to contain `---` further down is
  * left alone. The `type` field is read wherever it appears at the start of a
  * frontmatter line, so both the current `metadata.type` nesting and the older
- * top-level `type:` layout parse.
+ * top-level `type:` layout parse. Field values wrapped in one pair of matching
+ * quotes are unquoted — the store carries `description: "…"` files, and the
+ * raw value used to come back with its quotes baked in.
  */
 export function parseMemory(text: string): Memory {
-	const lines = text.split(/\r?\n/);
-	if (lines[0] !== "---") {
-		return { name: "", description: "", type: "", body: text.trim() };
-	}
-
-	let close = -1;
-	const limit = Math.min(lines.length, FRONTMATTER_MAX_LINES);
-	for (let i = 1; i < limit; i++) {
-		if (lines[i] === "---") {
-			close = i;
-			break;
-		}
-	}
-	if (close === -1) {
-		return { name: "", description: "", type: "", body: text.trim() };
-	}
+	const { frontmatter, body } = splitFrontmatter(text);
+	if (!frontmatter) return { name: "", description: "", type: "", body: text.trim() };
 
-	const frontmatter = lines.slice(1, close).join("\n");
+	const fm = frontmatter.join("\n");
 	const field = (key: string): string => {
-		const found = new RegExp(`^\\s*${key}:\\s*(.*)$`, "m").exec(frontmatter);
-		return found ? found[1].trim() : "";
+		const found = new RegExp(`^\\s*${key}:\\s*(.*)$`, "m").exec(fm);
+		if (!found) return "";
+		let value = found[1].trim();
+		if (
+			value.length >= 2 &&
+			((value.startsWith('"') && value.endsWith('"')) ||
+				(value.startsWith("'") && value.endsWith("'")))
+		) {
+			value = value.slice(1, -1);
+		}
+		return value.trim();
 	};
 
-	const body = lines
-		.slice(close + 1)
-		.join("\n")
-		.replace(/^\s*\n/, "")
-		.trimEnd();
-
 	return {
 		name: field("name"),
 		description: field("description"),
@@ -173,23 +290,30 @@ export function parseMemory(text: string): Memory {
 }
 
 /** Render a memory in the frontmatter shape Claude Code writes and reads. */
-export function serializeMemory(input: {
-	name: string;
-	description: string;
-	type?: string;
-	body?: string;
-}): string {
-	return [
-		"---",
-		`name: ${input.name}`,
-		`description: ${input.description}`,
-		"metadata:",
-		"  node_type: memory",
-		`  type: ${input.type || DEFAULT_TYPE}`,
-		"---",
-		"",
-		`${(input.body ?? "").trim()}\n`,
-	].join("\n");
+export function serializeMemory(
+	input: {
+		name: string;
+		description: string;
+		type?: string;
+		body?: string;
+	},
+	previousRaw?: string,
+): string {
+	// Start from the previous frontmatter when updating, so fields this
+	// extension does not model (originSessionId, custom metadata) survive.
+	const prev = previousRaw ? splitFrontmatter(previousRaw) : null;
+	const fm = prev?.frontmatter ? [...prev.frontmatter] : [];
+	const type = input.type || DEFAULT_TYPE;
+
+	setTopLevelKey(fm, "name", input.name);
+	setTopLevelKey(fm, "description", input.description);
+	// Older layout kept `type` top-level; keep such a line in step when present.
+	if (fm.some((line) => /^type:/.test(line))) setTopLevelKey(fm, "type", type);
+	setNestedKey(fm, "metadata", "node_type", "memory");
+	setNestedKey(fm, "metadata", "type", type);
+	setNestedKey(fm, "metadata", "modified", new Date().toISOString());
+
+	return ["---", ...fm, "---", "", `${(input.body ?? "").trim()}\n`].join("\n");
 }
 
 /** v1 is flat-only: one directory, single-segment names. */
@@ -201,6 +325,28 @@ function assertSafeName(name: string): void {
 	}
 }
 
+function isSafeName(name: string): boolean {
+	return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !name.includes("..");
+}
+
+/**
+ * Names that must keep throwing on sight — traversal, separators, absolute
+ * paths, hidden files, the reserved MEMORY index name. Everything else that
+ * fails the safe-name charset (spaces, punctuation, unicode) is merely an
+ * alias candidate: it can only match a frontmatter `name:`, never a path.
+ */
+function isDangerousName(name: string): boolean {
+	return (
+		name === "" ||
+		name.includes("\0") ||
+		name.includes("..") ||
+		/[\\/]/.test(name) ||
+		/^[A-Za-z]:/.test(name) ||
+		name.startsWith(".") ||
+		name.toUpperCase() === "MEMORY"
+	);
+}
+
 /**
  * Validate a memory name and resolve its file path inside `dir`, refusing
  * anything that escapes the directory — including through a symbolic link
@@ -211,24 +357,27 @@ function memoryFile(dir: string, name: string): string {
 	return resolveMemoryFilePath(dir, name).filePath;
 }
 
+/**
+ * Resolve an address to an existing memory file: by file stem first (the
+ * canonical address), then by frontmatter `name:` match. Security-rejected
+ * names throw exactly as the direct path always did; a merely non-charset
+ * name (spaces, hyphens-vs-underscores skew) falls through to the alias scan.
+ */
+function findMemoryFile(dir: string, name: string): string | null {
+	if (isDangerousName(name)) memoryFile(dir, name); // throws
+	if (isSafeName(name)) {
+		const { filePath } = resolveMemoryFilePath(dir, name);
+		if (fs.existsSync(filePath)) return filePath;
+	}
+	for (const entry of listMemoryFiles(dir)) {
+		if (entry.memory.name === name) return entry.filePath;
+	}
+	return null;
+}
+
 /** Every memory in the directory, sorted by name. Missing directory yields []. */
 export function listMemories(dir: string): Memory[] {
-	if (!fs.existsSync(dir)) return [];
-	return fs
-		.readdirSync(dir)
-		.filter((file) => file.endsWith(".md") && file !== INDEX_FILE)
-		.filter((file) => {
-			try {
-				return !fs.lstatSync(path.join(dir, file)).isSymbolicLink();
-			} catch {
-				return false;
-			}
-		})
-		.sort()
-		.map((file) => {
-			const parsed = parseMemory(fs.readFileSync(path.join(dir, file), "utf8"));
-			return { ...parsed, name: parsed.name || path.basename(file, ".md") };
-		});
+	return listMemoryFiles(dir).map((entry) => entry.memory);
 }
 
 /** Read the index file verbatim, or "" when it does not exist yet. */
@@ -238,10 +387,11 @@ export function readIndex(dir: string): string {
 }
 
 export function readMemory(dir: string, name: string): Memory | null {
-	const file = memoryFile(dir, name);
-	if (!fs.existsSync(file)) return null;
-	const parsed = parseMemory(fs.readFileSync(file, "utf8"));
-	return { ...parsed, name: parsed.name || name };
+	const filePath = findMemoryFile(dir, name);
+	if (!filePath) return null;
+	const stem = path.basename(filePath, ".md");
+	const parsed = parseMemory(fs.readFileSync(filePath, "utf8"));
+	return { ...parsed, name: parsed.name || stem, file: stem };
 }
 
 export interface WriteMemoryResult {
@@ -276,13 +426,19 @@ export function memoryDeletedSummary(name: string, existed: boolean): string {
  * empty. Returns true when a memory file existed.
  */
 export function deleteMemory(dir: string, name: string): boolean {
-	const file = memoryFile(dir, name);
-	const existed = fs.existsSync(file);
-	if (existed) fs.rmSync(file);
-
+	const filePath = findMemoryFile(dir, name);
+	const existed = filePath !== null;
+	if (filePath) fs.rmSync(filePath);
+
+	// Clean both the resolved stem's line and (harmlessly) a line keyed by the
+	// literal name, so an orphaned pointer can never survive either spelling.
+	const stems = new Set<string>();
+	if (filePath) stems.add(path.basename(filePath, ".md"));
+	if (isSafeName(name)) stems.add(name);
 	const indexFile = path.join(dir, INDEX_FILE);
-	if (fs.existsSync(indexFile)) {
-		const cleaned = removeIndexLine(fs.readFileSync(indexFile, "utf8"), `${name}.md`);
+	if (fs.existsSync(indexFile) && stems.size > 0) {
+		let cleaned = fs.readFileSync(indexFile, "utf8");
+		for (const stem of stems) cleaned = removeIndexLine(cleaned, `${stem}.md`);
 		if (cleaned === "") fs.rmSync(indexFile);
 		else fs.writeFileSync(indexFile, cleaned);
 	}
@@ -291,10 +447,16 @@ export function deleteMemory(dir: string, name: string): boolean {
 
 /** Write (or overwrite) a memory and register it in the index. */
 export function writeMemory(dir: string, input: WriteMemoryInput): WriteMemoryResult {
-	const file = memoryFile(dir, input.name);
+	assertSafeName(input.name);
 	fs.mkdirSync(dir, { recursive: true });
 
-	const previous = readMemory(dir, input.name);
+	// Resolve the target by stem OR frontmatter name so an update addressed
+	// by either spelling rewrites the same file instead of forking a second one.
+	const existing = findMemoryFile(dir, input.name);
+	const stem = existing ? path.basename(existing, ".md") : input.name;
+	const previousRaw = existing ? fs.readFileSync(existing, "utf8") : undefined;
+	const previous = existing && previousRaw !== undefined ? parseMemory(previousRaw) : null;
+	const filePath = existing ?? memoryFile(dir, input.name);
 
 	const memory: Memory = {
 		name: input.name,
@@ -302,15 +464,16 @@ export function writeMemory(dir: string, input: WriteMemoryInput): WriteMemoryRe
 		// that forgets the summary should not silently blank it. Sanitized so a
 		// description can never smuggle extra frontmatter keys into the file.
 		description: sanitizeInline(input.description ?? "") || previous?.description || "",
-		type: input.type || DEFAULT_TYPE,
+		type: input.type || previous?.type || DEFAULT_TYPE,
 		body: input.body.trim(),
+		file: stem,
 	};
 
-	fs.writeFileSync(file, serializeMemory(memory));
+	fs.writeFileSync(filePath, serializeMemory(memory, previousRaw));
 
 	const index = upsertIndexLine(readIndex(dir), {
 		title: sanitizeInline(input.title ?? "") || input.name,
-		file: `${input.name}.md`,
+		file: `${stem}.md`,
 		hook: sanitizeInline(input.hook ?? "") || sanitizeInline(input.description ?? "") || "",
 	});
 	fs.writeFileSync(path.join(dir, INDEX_FILE), index);
@@ -333,7 +496,7 @@ export function buildMemoryPrompt(dir: string): string | null {
 		: listMemories(dir).map((memory) =>
 				renderIndexLine({
 					title: memory.name,
-					file: `${memory.name}.md`,
+					file: `${memory.file ?? memory.name}.md`,
 					hook: memory.description,
 				}),
 			);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-claude-store",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Pi extension that reads and writes Claude Code's auto-memory store, keyed the way Claude Code keys it (canonical git root, Claude Code's sanitizePath)",
 	"author": "yg-codes",
 	"license": "MIT",