pi-claude-store 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yg-codes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,30 @@
+NOTICE — Derivative works
+
+This project derives from two MIT-licensed projects. Their copyright notices
+are preserved in the headers of the derived files and recorded here.
+
+1. elecnix/pi-claude-memory — Copyright (c) 2026 Nicolas Marchildon
+   https://github.com/elecnix/pi-claude-memory
+
+   Derived files:
+   - extensions/claude-store/index.ts (verbatim tool registration, index
+     injection, and TUI rendering)
+   - extensions/claude-store/memory-core.ts (base store logic)
+   - tests/memory-core.test.ts (base test suite, 37 tests)
+   - README.md (adapted)
+
+2. kuitos/opencode-claude-memory — Copyright (c) 2025 kuitos
+   https://github.com/kuitos/opencode-claude-memory
+
+   Derived files:
+   - extensions/claude-store/paths.ts (ported from src/store/paths.ts;
+     sanitizePath/findGitRoot/resolveCanonicalRoot are that project's
+     byte-for-byte ports of Claude Code's own implementations)
+   - path-resolution and file-name-validation portions of
+     extensions/claude-store/memory-core.ts
+   - tests/paths.test.ts (ported from test/store/paths.test.ts, translated
+     from bun:test to node:test)
+   - tests/helpers.ts (minimal port of test/helpers/ temp-dir helpers)
+
+When editing any derived file, keep the attribution header and this notice
+in sync with reality.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# pi-claude-store
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A pi extension that reads and writes **Claude Code's own memory store** — the
+same files, so a memory saved in either agent is immediately visible to the
+other. Not a parallel store, not a sync job.
+
+Derived from [elecnix/pi-claude-memory](https://github.com/elecnix/pi-claude-memory)
+(MIT, Copyright (c) 2026 Nicolas Marchildon) with the path-resolution layer
+ported from [kuitos/opencode-claude-memory](https://github.com/kuitos/opencode-claude-memory)
+(MIT, Copyright (c) 2025 kuitos). See [NOTICE](NOTICE) for the derivation
+record.
+
+## What it does
+
+Mirrors Claude Code's two-tier design, so a large store stays cheap:
+
+- **Index injected once per session.** The `MEMORY.md` pointer lines are added
+  to pi's system prompt at the first turn — titles and one-line hooks only,
+  never the bodies.
+- **Bodies read on demand.** `memory_read` fetches one memory when the index
+  suggests it is relevant.
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `memory_read` | Read one memory by name |
+| `memory_write` | Save or update a memory, or delete it with an empty/null body |
+| `memory_list` | List every memory with its description |
+
+Tool output is compact by default and expands with `ctrl+o`
+(`app.tools.expand`). `memory_write` shows the new body — or a diff when
+updating — and `memory_read` shows the full body.
+
+## Keying: the difference from upstream
+
+Claude Code keys the store by the **canonical git root** and slugifies it
+with `sanitizePath()` (every non-alphanumeric character becomes a dash, with a
+djb2 hash suffix past 200 characters). `pi-claude-memory` 0.1.x instead
+slugified the raw cwd with only `/` and `.` replaced, which silently splits
+the store whenever:
+
+- the path contains `_`, spaces, or other non-alphanumerics,
+- pi is launched from a repository subdirectory, or
+- pi runs inside a git worktree (upstream
+  [issue #14](https://github.com/elecnix/pi-claude-memory/issues/14)).
+
+This extension ports Claude Code's exact resolution (`sanitizePath`,
+`findGitRoot`, `resolveCanonicalRoot` from the kuitos port, which reproduces
+Claude Code's own implementations byte for byte), so pi, Claude Code, and the
+opencode plugin all resolve the identical store directory — worktrees
+included.
+
+The memory-file parser also matches Claude Code's `memoryScan.ts` rules:
+frontmatter is only recognised when the closing `---` appears within the
+first 30 lines, and both the current `metadata.type` nesting and the older
+top-level `type:` layout are read.
+
+## Scoping
+
+Memories are per-project and do not follow you between directories — the same
+rule that applies in Claude Code. Outside a git repository the store is keyed
+by the directory itself.
+
+## Install
+
+```bash
+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
+npm test
+```
+
+Tests have zero dependencies beyond Node (v22.6+ for native TypeScript
+stripping). They port both upstream suites — elecnix's 37 store tests and
+kuitos's path-resolution fixtures — and are the tripwire for Claude Code
+changing the on-disk memory format.
+
+## License
+
+MIT. Contains code derived from two MIT projects; see [NOTICE](NOTICE).

package/extensions/claude-store/index.ts

@@ -0,0 +1,318 @@
+/**
+ * Claude Store Extension
+ *
+ * Derived from elecnix/pi-claude-memory (MIT, Copyright (c) 2026 Nicolas
+ * Marchildon), extensions/claude-memory/index.ts — tool registration, index
+ * injection, and TUI rendering are his, unchanged. See NOTICE for the full
+ * derivation record.
+ *
+ * Gives pi read and write access to Claude Code's auto-memory store — the
+ * same ~/.claude/projects/<slug>/memory/ directory Claude Code uses.
+ * One store, two agents, no sync step.
+ *
+ * Mirrors Claude Code's own two-tier design: the MEMORY.md index is injected
+ * into the system prompt once per session, and bodies are fetched on demand
+ * with `memory_read`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	generateDiffString,
+	keyHint,
+	withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import path from "node:path";
+
+import {
+	buildMemoryPrompt,
+	deleteMemory,
+	listMemories,
+	memoryDeletedSummary,
+	memoryDirFor,
+	memorySummary,
+	readMemory,
+	writeMemory,
+} from "./memory-core.ts";
+
+export default function (pi: ExtensionAPI) {
+	let injected = false;
+
+	pi.on("session_start", async () => {
+		injected = false;
+	});
+
+	// Inject the index once per session, not once per turn — the store does not
+	// change often, and re-injecting would grow the prompt on every exchange.
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (injected) return;
+		injected = true;
+
+		const prompt = buildMemoryPrompt(memoryDirFor(ctx.cwd));
+		if (!prompt) return;
+
+		return { systemPrompt: `${event.systemPrompt}\n\n${prompt}` };
+	});
+
+	pi.registerTool({
+		name: "memory_read",
+		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.",
+		promptSnippet: "Read a stored memory by name",
+		promptGuidelines: [
+			"Call memory_read when an entry in the memory index looks relevant to the current task.",
+		],
+		parameters: Type.Object({
+			name: Type.String({ description: "Memory name, e.g. no-claude-pr-signature" }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const dir = memoryDirFor(ctx.cwd);
+			try {
+				const memory = readMemory(dir, params.name);
+				if (!memory) {
+					const known = listMemories(dir).map((m) => m.name);
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: known.length
+									? `No memory named "${params.name}". Available: ${known.join(", ")}`
+									: `No memory named "${params.name}". The store is empty.`,
+							},
+						],
+						details: {},
+					};
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `${memory.description}\n\n${memory.body}`,
+						},
+					],
+					details: {
+						name: memory.name,
+						type: memory.type,
+						description: memory.description,
+						body: memory.body,
+					},
+				};
+			} catch (error) {
+				return {
+					content: [{ type: "text" as const, text: `${(error as Error).message}` }],
+					details: {},
+				};
+			}
+		},
+
+		renderResult(result, { expanded, isPartial }, theme, _context) {
+			if (isPartial) return new Text(theme.fg("warning", "Reading..."), 0, 0);
+			const details = result.details as
+				| { name?: string; description?: string; body?: string }
+				| undefined;
+
+			const collapsed = theme.fg(
+				"success",
+				`${details?.name ?? "memory"}: ${details?.description ?? ""}`,
+			);
+			if (!expanded || !details?.body) {
+				return new Text(
+					`${collapsed} ${theme.fg("dim", `(${keyHint("app.tools.expand", "expand")})`)}`,
+					0,
+					0,
+				);
+			}
+			return new Text(`${collapsed}\n${theme.fg("dim", details.body)}`, 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_write",
+		label: "Write memory",
+		description:
+			"Save a durable fact to the memory store shared with Claude Code. Use for preferences, " +
+			"project constraints, and guidance you were given — not for things the repo or git " +
+			"history already records, and not for details that only matter in this conversation. " +
+			"Pass an empty or null body to delete the memory instead.",
+		promptSnippet: "Save a durable fact to shared memory",
+		promptGuidelines: [
+			"Call memory_write when the user states a lasting preference or correction worth keeping across sessions.",
+			"Call memory_write with an empty or null body to delete a memory that is no longer wanted.",
+		],
+		parameters: Type.Object({
+			name: Type.String({ description: "Short kebab-case slug, e.g. prefers-tabs-over-spaces" }),
+			description: Type.Optional(
+				Type.String({
+					description:
+						"One line summarizing the fact. Used to decide relevance during recall. " +
+						"Omit when deleting.",
+				}),
+			),
+			body: Type.Optional(
+				Type.Union([
+					Type.String({
+						description:
+							"The fact itself. For feedback and project types, follow with **Why:** and " +
+							"**How to apply:** lines.",
+					}),
+					Type.Null({
+						description: "Pass null or an empty string to delete the memory.",
+					}),
+				]),
+			),
+			type: Type.Optional(
+				Type.String({ description: "One of: user, feedback, project, reference" }),
+			),
+			title: Type.Optional(Type.String({ description: "Index title. Defaults to the name." })),
+			hook: Type.Optional(
+				Type.String({ description: "Short index hook. Defaults to the description." }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const dir = memoryDirFor(ctx.cwd);
+
+			// memory_write mutates MEMORY.md read-modify-write, so two calls in one
+			// turn would race and lose an index line without this queue.
+			return withFileMutationQueue(path.join(dir, "MEMORY.md"), async () => {
+				try {
+					// An empty or null body means "delete this memory" — no separate tool.
+					if (params.body === undefined || params.body === null || params.body.trim() === "") {
+						const existed = deleteMemory(dir, params.name);
+						return {
+							content: [
+								{
+									type: "text" as const,
+									text: memoryDeletedSummary(params.name, existed),
+								},
+							],
+							details: { name: params.name, dir, deleted: true, existed },
+						};
+					}
+
+					const { memory, previous, created } = writeMemory(dir, {
+						...params,
+						body: params.body,
+					});
+					const diff =
+						previous === null
+							? undefined
+							: generateDiffString(previous.body, memory.body).diff;
+					return {
+						content: [
+							{ type: "text" as const, text: memorySummary(params.name, created) },
+						],
+						details: {
+							name: params.name,
+							dir,
+							created,
+							diff,
+							body: memory.body,
+						},
+					};
+				} catch (error) {
+					return {
+						content: [
+							{ type: "text" as const, text: `Could not save: ${(error as Error).message}` },
+						],
+						details: {},
+					};
+				}
+			});
+		},
+
+		renderResult(result, { expanded, isPartial }, theme, _context) {
+			if (isPartial) return new Text(theme.fg("warning", "Writing..."), 0, 0);
+			const details = result.details as
+				| {
+						name?: string;
+						created?: boolean;
+						diff?: string;
+						body?: string;
+						deleted?: boolean;
+						existed?: boolean;
+				  }
+				| undefined;
+
+			if (!details?.name) {
+				const content = result.content[0];
+				return new Text(
+					theme.fg("error", content?.type === "text" ? content.text : "Failed"),
+					0,
+					0,
+				);
+			}
+
+			if (details.deleted) {
+				const text = memoryDeletedSummary(details.name, details.existed ?? false);
+				return new Text(
+					theme.fg(details.existed ? "success" : "warning", text),
+					0,
+					0,
+				);
+			}
+
+			const summary = theme.fg(
+				"success",
+				memorySummary(details.name, details.created ?? true),
+			);
+
+			if (!expanded) {
+				return new Text(
+					`${summary} ${theme.fg("dim", `(${keyHint("app.tools.expand", "expand")})`)}`,
+					0,
+					0,
+				);
+			}
+
+			// Show a diff when updating an existing memory, otherwise the new body.
+			if (details.diff) {
+				const lines = details.diff.split("\n").slice(0, 30);
+				let text = summary;
+				for (const line of lines) {
+					if (line.startsWith("+")) {
+						text += `\n${theme.fg("success", line)}`;
+					} else if (line.startsWith("-")) {
+						text += `\n${theme.fg("error", line)}`;
+					} else {
+					text += `\n${theme.fg("dim", line)}`;
+				}
+				}
+				const total = details.diff.split("\n").length;
+				if (total > 30) {
+					text += `\n${theme.fg("muted", `... ${total - 30} more diff lines`)}`;
+				}
+				return new Text(text, 0, 0);
+			}
+
+			return new Text(`${summary}\n${theme.fg("dim", details.body ?? "")}`, 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_list",
+		label: "List memories",
+		description:
+			"List every memory in the store shared with Claude Code, with its description. " +
+			"Use when the injected index looks incomplete or stale.",
+		promptSnippet: "List all stored memories",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const memories = listMemories(memoryDirFor(ctx.cwd));
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: memories.length
+							? memories.map((m) => `- ${m.name} — ${m.description}`).join("\n")
+							: "No memories stored for this project.",
+					},
+				],
+				details: { count: memories.length },
+			};
+		},
+	});
+}

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

@@ -0,0 +1,356 @@
+/**
+ * Core logic for reading and writing Claude Code's auto-memory store.
+ *
+ * Derived from elecnix/pi-claude-memory (MIT, Copyright (c) 2026 Nicolas
+ * Marchildon), extensions/claude-memory/memory-core.ts. Directory resolution
+ * and file-name validation are ported from kuitos/opencode-claude-memory
+ * (MIT, Copyright (c) 2025 kuitos), src/store/paths.ts.
+ *
+ * Claude Code keeps one memory per file under
+ * ~/.claude/projects/<sanitized-canonical-git-root>/memory/, alongside a
+ * MEMORY.md index that holds one pointer line per memory. Only the index is
+ * loaded at session start; bodies are read on demand. This module reproduces
+ * that layout exactly so pi and Claude Code share a single store — keyed the
+ * same way Claude Code keys it: by canonical git root (worktrees resolve to
+ * the main repository), with Claude Code's own sanitizePath() slug.
+ *
+ * Pure functions plus thin fs wrappers — no pi imports, so it is testable
+ * with plain `node --test`.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { findCanonicalGitRoot, resolveMemoryFilePath, sanitizePath } from "./paths.ts";
+
+export interface IndexEntry {
+	title: string;
+	file: string;
+	hook: string;
+}
+
+export interface Memory {
+	name: string;
+	description: string;
+	type: string;
+	body: string;
+}
+
+export interface WriteMemoryInput {
+	name: string;
+	description?: string;
+	body: string;
+	type?: string;
+	title?: string;
+	hook?: string;
+}
+
+const INDEX_FILE = "MEMORY.md";
+const DEFAULT_TYPE = "project";
+
+/** Claude Code's memoryScan.ts only recognises frontmatter whose closing delimiter is within the first 30 lines. */
+export const FRONTMATTER_MAX_LINES = 30;
+
+/**
+ * Resolve the Claude Code memory directory for a working directory.
+ *
+ * Claude Code keys the store by the canonical git root — a linked worktree or
+ * a subdirectory of the repository resolves to the repository root — and only
+ * falls back to the directory itself outside a repository. The slug is Claude
+ * Code's own sanitizePath(): every non-alphanumeric character becomes a dash,
+ * with a djb2 hash suffix past 200 characters.
+ */
+export function memoryDirFor(cwd: string): string {
+	const root = findCanonicalGitRoot(cwd) ?? path.resolve(cwd);
+	return path.join(os.homedir(), ".claude", "projects", sanitizePath(root), "memory");
+}
+
+/** Parse `- [Title](file.md) — hook` pointer lines, ignoring anything else. */
+export function parseIndex(md: string): IndexEntry[] {
+	const entries: IndexEntry[] = [];
+	for (const line of md.split("\n")) {
+		const match = /^\s*-\s*\[([^\]]*)\]\(([^)]+)\)\s*(?:—\s*(.*))?$/.exec(line);
+		if (!match) continue;
+		entries.push({
+			title: match[1].trim(),
+			file: match[2].trim(),
+			hook: (match[3] ?? "").trim(),
+		});
+	}
+	return entries;
+}
+
+/**
+ * Collapse newlines and other control characters to single spaces, keeping
+ * index and frontmatter fields single-line. Index pointer lines are injected
+ * into pi's system prompt; a multi-line title or hook written by any of the
+ * agents sharing the store could otherwise forge additional index entries
+ * (second-order prompt injection — SEC-001, docs/security/2026-10-09-review.md).
+ */
+function sanitizeInline(value: string): string {
+	return value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/ {2,}/g, " ").trim();
+}
+
+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, "");
+	const hook = sanitizeInline(entry.hook);
+	const file = sanitizeInline(entry.file);
+	return hook ? `- [${title}](${file}) — ${hook}` : `- [${title}](${file})`;
+}
+
+/** Replace the pointer line for `entry.file` if present, otherwise append it. */
+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 parsed = parseIndex(line)[0];
+		if (parsed && parsed.file === entry.file) {
+			replaced = true;
+			return rendered;
+		}
+		return line;
+	});
+
+	if (!replaced) next.push(rendered);
+	return `${next.join("\n")}\n`;
+}
+
+/**
+ * Split a memory file into its frontmatter fields and body.
+ *
+ * Frontmatter is only recognised when the opening `---` is the first line and
+ * the closing `---` appears within the first FRONTMATTER_MAX_LINES lines —
+ * 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.
+ */
+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 = lines.slice(1, close).join("\n");
+	const field = (key: string): string => {
+		const found = new RegExp(`^\\s*${key}:\\s*(.*)$`, "m").exec(frontmatter);
+		return found ? found[1].trim() : "";
+	};
+
+	const body = lines
+		.slice(close + 1)
+		.join("\n")
+		.replace(/^\s*\n/, "")
+		.trimEnd();
+
+	return {
+		name: field("name"),
+		description: field("description"),
+		type: field("type"),
+		body,
+	};
+}
+
+/** 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");
+}
+
+/** v1 is flat-only: one directory, single-segment names. */
+function assertSafeName(name: string): void {
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes("..")) {
+		throw new Error(
+			`Invalid memory name "${name}": use a kebab-case slug with no path separators.`,
+		);
+	}
+}
+
+/**
+ * Validate a memory name and resolve its file path inside `dir`, refusing
+ * anything that escapes the directory — including through a symbolic link
+ * planted inside it (ported containment check from kuitos).
+ */
+function memoryFile(dir: string, name: string): string {
+	assertSafeName(name);
+	return resolveMemoryFilePath(dir, name).filePath;
+}
+
+/** 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") };
+		});
+}
+
+/** Read the index file verbatim, or "" when it does not exist yet. */
+export function readIndex(dir: string): string {
+	const file = path.join(dir, INDEX_FILE);
+	return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+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 };
+}
+
+export interface WriteMemoryResult {
+	memory: Memory;
+	previous: Memory | null;
+	created: boolean;
+}
+
+/** Drop the pointer line for `file` from the index, preserving the rest. */
+export function removeIndexLine(md: string, file: string): string {
+	const kept = md.split("\n").filter((line) => {
+		const parsed = parseIndex(line)[0];
+		return !(parsed && parsed.file === file);
+	});
+	while (kept.length > 0 && kept[kept.length - 1].trim() === "") kept.pop();
+	return kept.length ? `${kept.join("\n")}\n` : "";
+}
+
+/** One-line summary shown for a memory_write tool result. */
+export function memorySummary(name: string, created: boolean): string {
+	return created ? `Saved memory "${name}".` : `Updated memory "${name}".`;
+}
+
+/** One-line summary shown when memory_write deletes a memory. */
+export function memoryDeletedSummary(name: string, existed: boolean): string {
+	return existed ? `Deleted memory "${name}".` : `No memory named "${name}" to delete.`;
+}
+
+/**
+ * Delete a memory: remove its file and drop its pointer line from the index.
+ * The index file itself is removed when it empties, so an empty store stays
+ * 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 indexFile = path.join(dir, INDEX_FILE);
+	if (fs.existsSync(indexFile)) {
+		const cleaned = removeIndexLine(fs.readFileSync(indexFile, "utf8"), `${name}.md`);
+		if (cleaned === "") fs.rmSync(indexFile);
+		else fs.writeFileSync(indexFile, cleaned);
+	}
+	return existed;
+}
+
+/** 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);
+	fs.mkdirSync(dir, { recursive: true });
+
+	const previous = readMemory(dir, input.name);
+
+	const memory: Memory = {
+		name: input.name,
+		// Omitted description keeps the previous one (or stays empty) — an update
+		// 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,
+		body: input.body.trim(),
+	};
+
+	fs.writeFileSync(file, serializeMemory(memory));
+
+	const index = upsertIndexLine(readIndex(dir), {
+		title: sanitizeInline(input.title ?? "") || input.name,
+		file: `${input.name}.md`,
+		hook: sanitizeInline(input.hook ?? "") || sanitizeInline(input.description ?? "") || "",
+	});
+	fs.writeFileSync(path.join(dir, INDEX_FILE), index);
+
+	return { memory, previous, created: previous === null };
+}
+
+/**
+ * Build the block injected into pi's system prompt: the index only, never the
+ * bodies. This mirrors how Claude Code loads memory — a table of contents up
+ * front, full text pulled on demand — so a large store stays cheap.
+ *
+ * Returns null when the directory holds no memories, so the caller can leave
+ * the prompt untouched.
+ */
+export function buildMemoryPrompt(dir: string): string | null {
+	const indexed = parseIndex(readIndex(dir));
+	const lines = indexed.length
+		? indexed.map((entry) => renderIndexLine(entry))
+		: listMemories(dir).map((memory) =>
+				renderIndexLine({
+					title: memory.name,
+					file: `${memory.name}.md`,
+					hook: memory.description,
+				}),
+			);
+
+	if (lines.length === 0) return null;
+
+	return [
+		"## Memory",
+		"",
+		"You share a persistent memory store with Claude Code for this project.",
+		"Below is the index — one line per memory, bodies not included.",
+		"",
+		...lines,
+		"",
+		"Call `memory_read` with a name (the filename without `.md`) when an entry",
+		"looks relevant to the task at hand. Call `memory_write` to record a durable",
+		"fact — a preference, a project constraint, or guidance you were given.",
+		"Do not record what the repo or git history already says.",
+	].join("\n");
+}

package/extensions/claude-store/paths.ts

@@ -0,0 +1,221 @@
+/**
+ * Claude Code compatible memory directory path resolution.
+ *
+ * Ported from kuitos/opencode-claude-memory (MIT, Copyright (c) 2025 kuitos),
+ * src/store/paths.ts. sanitizePath(), findGitRoot() and resolveCanonicalRoot()
+ * are that project's byte-for-byte ports of Claude Code's own implementations
+ * (utils/sessionStoragePortable.ts and utils/git.ts), so pi resolves exactly
+ * the memory directory Claude Code resolves — including git worktrees, which
+ * key to the main repository root.
+ *
+ * Pure functions only: no directory creation, no environment access.
+ * memory-core.ts owns the side effects.
+ */
+
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+
+const MAX_SANITIZED_LENGTH = 200;
+
+// Memory file names may be relative sub-paths (`team/conventions`), matching
+// Claude Code, which reads memory directories recursively. Every segment is
+// validated; the result always uses `/`. (The extension itself is flat-only
+// in v1 — memory-core enforces that on top of this function.)
+export function validateMemoryFileName(fileName: string): string {
+	if (typeof fileName !== "string" || fileName.length === 0) {
+		throw new Error("Memory file name cannot be empty");
+	}
+	if (fileName.includes("\0")) {
+		throw new Error(`Memory file name must not contain null bytes: ${fileName}`);
+	}
+	if (isAbsolute(fileName) || /^[A-Za-z]:/.test(fileName) || /^[\\/]/.test(fileName)) {
+		throw new Error(`Memory file name must be relative to the memory directory: ${fileName}`);
+	}
+
+	const segments = fileName.split(/[\\/]/);
+	const last = segments.length - 1;
+	for (let i = 0; i < segments.length; i++) {
+		let segment = segments[i] ?? "";
+		if (i === last && segment.endsWith(".md")) segment = segment.slice(0, -3);
+		if (segment.length === 0) {
+			throw new Error(`Memory file name must not contain empty path segments: ${fileName}`);
+		}
+		if (segment === "." || segment.includes("..")) {
+			throw new Error(`Memory file name must not contain path traversal: ${fileName}`);
+		}
+		if (segment.startsWith(".")) {
+			throw new Error(`Memory file name segments must not start with '.': ${fileName}`);
+		}
+		segments[i] = segment;
+	}
+
+	if ((segments[last] ?? "").toUpperCase() === "MEMORY") {
+		throw new Error("'MEMORY' is a reserved name and cannot be used as a memory file name");
+	}
+
+	return `${segments.join("/")}.md`;
+}
+
+function canonical(path: string): string | undefined {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return undefined;
+	}
+}
+
+function existsNoFollow(path: string): boolean {
+	try {
+		lstatSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isInside(path: string, root: string): boolean {
+	return path === root || path.startsWith(root + sep);
+}
+
+// Validates the name and resolves it inside `memoryDir`, refusing anything
+// that escapes it.
+//
+// Lexical containment (`resolve` + prefix) is not enough once sub-directories
+// are allowed: a symbolic link inside the memory directory (`team -> /elsewhere`)
+// would let `team/x` read, overwrite or delete a file outside it. The deepest
+// existing path component is therefore resolved through the filesystem and
+// must land inside the *real* memory directory. Links that stay inside the
+// memory directory are fine; a dangling link is rejected because writing
+// through it would create a file wherever it points.
+export function resolveMemoryFilePath(
+	memoryDir: string,
+	fileName: string,
+): { relativePath: string; filePath: string } {
+	const relativePath = validateMemoryFileName(fileName);
+	const root = resolve(memoryDir);
+	const filePath = resolve(root, ...relativePath.split("/"));
+	if (!filePath.startsWith(root + sep)) {
+		throw new Error(`Memory file name resolves outside the memory directory: ${fileName}`);
+	}
+
+	const realRoot = canonical(root);
+	if (realRoot !== undefined) {
+		let probe = filePath;
+		while (probe !== root && !existsNoFollow(probe)) probe = dirname(probe);
+		const realProbe = canonical(probe);
+		if (realProbe === undefined || !isInside(realProbe, realRoot)) {
+			throw new Error(`Memory file name resolves outside the memory directory: ${fileName}`);
+		}
+	}
+	return { relativePath, filePath };
+}
+
+// Exact copy of Claude Code's djb2Hash() from utils/hash.ts
+function djb2Hash(str: string): number {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+	}
+	return hash;
+}
+
+function simpleHash(str: string): string {
+	return Math.abs(djb2Hash(str)).toString(36);
+}
+
+// Exact copy of Claude Code's sanitizePath() from utils/sessionStoragePortable.ts
+export function sanitizePath(name: string): string {
+	const sanitized = name.replace(/[^a-zA-Z0-9]/g, "-");
+	if (sanitized.length <= MAX_SANITIZED_LENGTH) {
+		return sanitized;
+	}
+	const hash = simpleHash(name);
+	return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${hash}`;
+}
+
+// Matches Claude Code's findGitRoot() from utils/git.ts
+export function findGitRoot(startPath: string): string | null {
+	let current = resolve(startPath);
+	const root = current.substring(0, current.indexOf(sep) + 1) || sep;
+
+	while (current !== root) {
+		try {
+			const gitPath = join(current, ".git");
+			const s = statSync(gitPath);
+			if (s.isDirectory() || s.isFile()) {
+				return current.normalize("NFC");
+			}
+		} catch {}
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+
+	try {
+		const gitPath = join(root, ".git");
+		const s = statSync(gitPath);
+		if (s.isDirectory() || s.isFile()) {
+			return root.normalize("NFC");
+		}
+	} catch {}
+
+	return null;
+}
+
+// Matches Claude Code's resolveCanonicalRoot() from utils/git.ts
+// Resolves worktrees to the main repo root via .git -> gitdir -> commondir chain
+function resolveCanonicalRoot(gitRoot: string): string {
+	try {
+		const gitContent = readFileSync(join(gitRoot, ".git"), "utf-8").trim();
+		if (!gitContent.startsWith("gitdir:")) {
+			return gitRoot;
+		}
+		const worktreeGitDir = resolve(gitRoot, gitContent.slice("gitdir:".length).trim());
+
+		const commonDir = resolve(
+			worktreeGitDir,
+			readFileSync(join(worktreeGitDir, "commondir"), "utf-8").trim(),
+		);
+
+		// SECURITY: validate worktreeGitDir is a direct child of <commonDir>/worktrees/
+		if (resolve(dirname(worktreeGitDir)) !== join(commonDir, "worktrees")) {
+			return gitRoot;
+		}
+
+		// SECURITY: validate gitdir back-link points to our .git
+		const backlink = realpathSync(readFileSync(join(worktreeGitDir, "gitdir"), "utf-8").trim());
+		if (backlink !== join(realpathSync(gitRoot), ".git")) {
+			return gitRoot;
+		}
+
+		// `commondir` is written by git with `/` separators even on Windows, so both the platform
+		// separator and `/` are checked (they are the same check on POSIX).
+		if (commonDir.endsWith(`${sep}.git`) || commonDir.endsWith("/.git")) {
+			return dirname(commonDir).normalize("NFC");
+		}
+
+		return commonDir.normalize("NFC");
+	} catch {
+		return gitRoot;
+	}
+}
+
+export function findCanonicalGitRoot(startPath: string): string | null {
+	const root = findGitRoot(startPath);
+	if (!root) return null;
+	return resolveCanonicalRoot(root);
+}
+
+export function isRootPath(path: string): boolean {
+	const resolved = resolve(path);
+	return resolved === parse(resolved).root;
+}
+
+// OpenCode reports worktree "/" for directories outside any git repository;
+// fall back to the directory so memory is not shared by every non-git project
+// on the machine. Kept for parity with the upstream port and its tests; pi
+// currently reports only a cwd, for which this is the identity.
+export function resolveMemoryRoot(worktree: string, directory: string): string {
+	if (isRootPath(worktree) && !isRootPath(directory)) return directory;
+	return worktree;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "pi-claude-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-claude-store",
+	"version": "0.1.1",
+	"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",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/yg-codes/pi-claude-store.git"
+	},
+	"homepage": "https://github.com/yg-codes/pi-claude-store#readme",
+	"bugs": {
+		"url": "https://github.com/yg-codes/pi-claude-store/issues"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-coding-agent",
+		"pi-extension",
+		"claude-code",
+		"memory"
+	],
+	"files": [
+		"extensions/",
+		"README.md",
+		"NOTICE"
+	],
+	"scripts": {
+		"test": "node --test tests/*.test.ts"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		}
+	}
+}