@amoree-code/ocean 0.0.0-stage → 1.2.0

package/node_modules/@ocean/brain/dist/memory/memory-harvest.js

@@ -0,0 +1,345 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { MemoryContractError } from "@ocean/core/domain/mcp/memory-contract.js";
+import { projectDir } from "@ocean/core/shared/paths.js";
+import { sha256 } from "./memory-audit.js";
+import { harvestLedgerFile, stagingDir } from "./memory-paths.js";
+import { proposeMemory } from "./memory-write.js";
+export const HARVEST_SOURCES = [
+    "claude-code",
+    "codex",
+    "gemini",
+    "hermes",
+    "antigravity",
+    "instructions",
+];
+// The same text with other spacing or letter case is the same memory.
+const normalizedKey = (text) => `n:${sha256(text.toLowerCase().replace(/\s+/g, " ").trim())}`;
+// A short label: the first heading, else a frontmatter name, else the first line.
+export function textTitle(text) {
+    const heading = /^#{1,6}\s+(.+)$/m.exec(text)?.[1];
+    const name = /^name:\s*["']?(.+?)["']?\s*$/m.exec(text)?.[1];
+    const first = text
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line && line !== "---");
+    return (heading ?? name ?? first ?? "").slice(0, 100);
+}
+const slug = (value) => value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50) || "note";
+// The frontmatter a pulled candidate carries, and the record it would become.
+function placementMeta(origin, placement) {
+    const project = placement.project ?? "unassigned";
+    const title = textTitle(origin.text);
+    const meta = {
+        client: origin.client,
+        project,
+        ...(placement.tags?.length ? { tags: placement.tags } : {}),
+        ...(placement.cwd ? { cwd: placement.cwd } : {}),
+        pull: true,
+        pulled_at: new Date().toISOString(),
+        ...(origin.date ? { date: origin.date } : {}),
+        title,
+        file: origin.file,
+    };
+    const target = placement.target
+        ? `${projectDir(project)}/memory/${slug(title)}-${sha256(origin.text).slice(0, 6)}.md`
+        : undefined;
+    return { meta, target, project, title };
+}
+const MAX_BYTES = 32_000;
+const TEXT = /\.(md|txt)$/i;
+async function filesIn(directory, depth = 0) {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    const found = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith("."))
+            continue;
+        const target = path.join(directory, entry.name);
+        if (entry.isFile() && TEXT.test(entry.name))
+            found.push(target);
+        else if (depth > 0 && entry.isDirectory())
+            found.push(...(await filesIn(target, depth - 1)));
+    }
+    return found;
+}
+// Global instruction files the owner may have written by hand. The block Ocean generates from
+// its own charter (`ai-sync` markers) and `@` includes of it are Ocean's already, not imported.
+const INSTRUCTION_FILES = [
+    ".claude/CLAUDE.md",
+    ".codex/AGENTS.md",
+    ".gemini/GEMINI.md",
+    ".qwen/QWEN.md",
+    ".config/opencode/AGENTS.md",
+];
+const GENERATED_BLOCK = /<!-- ai-sync:generated -->[\s\S]*?<!-- ai-sync:end -->/g;
+const GEMINI_MEMORIES = /^## Gemini Added Memories\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m;
+function ownedText(text) {
+    return text
+        .replace(GENERATED_BLOCK, "")
+        .replace(GEMINI_MEMORIES, "")
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("@"))
+        .join("\n")
+        .trim();
+}
+// A text over `max` bytes, cut at the shallowest heading level that splits it; a part still too
+// large is cut at the next level, then between paragraphs.
+export function splitMarkdown(text, max = MAX_BYTES) {
+    const size = (value) => Buffer.byteLength(value, "utf8");
+    if (size(text) <= max)
+        return [text];
+    for (const level of [1, 2, 3, 4]) {
+        const marker = new RegExp(`^#{${level}} `, "m");
+        const parts = text
+            .split(new RegExp(`(?=^#{${level}} )`, "m"))
+            .filter((part) => part.trim());
+        if (parts.length > 1 && parts.some((part) => marker.test(part)))
+            return parts.flatMap((part) => splitMarkdown(part, max));
+    }
+    // No heading left to cut at: group whole paragraphs. One paragraph still over the limit stays
+    // whole and is reported too large; text is never cut mid-paragraph.
+    const out = [];
+    let current = "";
+    for (const piece of text.split(/(?<=\n\n)/)) {
+        if (current && size(current + piece) > max) {
+            out.push(current);
+            current = "";
+        }
+        current += piece;
+    }
+    if (current.trim())
+        out.push(current);
+    return out;
+}
+// The texts each source holds, as (label, text) pairs. Missing stores are simply empty.
+async function sourceTexts(source, home) {
+    const read = async (files) => Promise.all(files.map(async (file) => ({ file, text: await readFile(file, "utf8") })));
+    if (source === "claude-code") {
+        const projects = path.join(home, ".claude", "projects");
+        const dirs = await readdir(projects).catch(() => []);
+        const files = [...(await filesIn(stagingDir("claude-code")))];
+        for (const dir of dirs.sort())
+            files.push(...(await filesIn(path.join(projects, dir, "memory"))).filter((file) => path.basename(file) !== "MEMORY.md"));
+        return read(files);
+    }
+    if (source === "codex")
+        // raw_memories.md concatenates the per-session rollout summaries: history, indexed by
+        // `ocean pull`, not memory.
+        return read((await filesIn(path.join(home, ".codex", "memories"))).filter((file) => path.basename(file) !== "raw_memories.md"));
+    if (source === "instructions") {
+        const texts = [];
+        for (const relative of INSTRUCTION_FILES) {
+            const file = path.join(home, relative);
+            const text = ownedText(await readFile(file, "utf8").catch(() => ""));
+            // Headings alone (what is left around a removed block) say nothing.
+            if (text.split("\n").some((line) => line.trim() && !/^#+\s/.test(line)))
+                texts.push({ file, text });
+        }
+        for (const file of await filesIn(path.join(home, ".cursor", "rules")))
+            texts.push({ file, text: await readFile(file, "utf8") });
+        return texts;
+    }
+    if (source === "hermes")
+        return read(await filesIn(path.join(home, ".hermes", "memories")));
+    if (source === "antigravity")
+        return read(await filesIn(path.join(home, ".gemini", "antigravity", "brain"), 1));
+    const texts = await read(await filesIn(path.join(home, ".gemini", "memory")));
+    // Gemini's save_memory appends under this heading in GEMINI.md.
+    const geminiMd = path.join(home, ".gemini", "GEMINI.md");
+    const section = GEMINI_MEMORIES.exec(await readFile(geminiMd, "utf8").catch(() => ""))?.[1];
+    if (section?.trim())
+        texts.push({ file: geminiMd, text: section.trim() });
+    return texts;
+}
+const ledgerFile = harvestLedgerFile;
+async function readLedger() {
+    return JSON.parse(await readFile(ledgerFile(), "utf8").catch(() => "{}"));
+}
+export async function harvestMemory(options = {}) {
+    const home = options.home ?? os.homedir();
+    const ledger = await readLedger();
+    const items = [];
+    const shown = (file) => file.startsWith(home) ? `~${file.slice(home.length)}` : file;
+    const parts = async (source) => {
+        const out = [];
+        for (const { file, text } of await sourceTexts(source, home)) {
+            const date = (await stat(file).catch(() => null))?.mtime
+                .toISOString()
+                .slice(0, 10);
+            const pieces = splitMarkdown(text);
+            pieces.forEach((piece, index) => {
+                out.push({
+                    path: file,
+                    file: pieces.length > 1 ? `${shown(file)}#${index + 1}` : shown(file),
+                    text: piece,
+                    date,
+                });
+            });
+        }
+        return out;
+    };
+    // Keys proposed in this run too, so one text found twice is proposed once.
+    const seen = new Set();
+    for (const source of options.sources ?? HARVEST_SOURCES) {
+        for (const { path: origin, file, text, date } of await parts(source)) {
+            if (!text.trim())
+                continue;
+            const bytes = Buffer.byteLength(text, "utf8");
+            const keys = [sha256(text), normalizedKey(text)];
+            const placed = placementMeta({ client: source, file, text, date }, options.classify?.({ client: source, file: origin, text }) ?? {});
+            const item = {
+                source,
+                file,
+                bytes,
+                status: "new",
+                project: placed.project,
+                title: placed.title,
+            };
+            if (keys.some((key) => ledger[key] || seen.has(key)))
+                item.status = "seen";
+            else if (bytes > MAX_BYTES)
+                item.status = "too-large";
+            else if (options.apply)
+                try {
+                    const proposed = await proposeMemory({
+                        content: text,
+                        origin: "imported",
+                        source,
+                        reason: `harvested from ${file}`.slice(0, 200),
+                        target: placed.target,
+                        meta: placed.meta,
+                    });
+                    for (const key of keys)
+                        ledger[key] = proposed.candidate;
+                    item.status = "proposed";
+                    item.candidate = proposed.candidate;
+                }
+                catch (error) {
+                    if (!(error instanceof MemoryContractError))
+                        throw error;
+                    item.status = error.code === "SECRET" ? "secret" : "too-large";
+                }
+            for (const key of keys)
+                seen.add(key);
+            items.push(item);
+        }
+    }
+    if (options.apply) {
+        await mkdir(path.dirname(ledgerFile()), { recursive: true, mode: 0o700 });
+        await writeFile(ledgerFile(), `${JSON.stringify(ledger, null, 2)}\n`, {
+            mode: 0o600,
+        });
+    }
+    return items;
+}
+// claude.ai account export (ASSUMED shape, read defensively): `projects.json` as a list of
+// projects with name, description, prompt_template and docs [{filename, content}]. Each project
+// and each doc becomes a candidate; anything unreadable is reported, never guessed.
+export async function importClaudeExport(directory, options = {}) {
+    const problems = [];
+    const items = [];
+    const file = path.join(directory, "projects.json");
+    if (!(await stat(file).catch(() => null))) {
+        problems.push("projects.json not found in the export");
+        return { items, problems };
+    }
+    let projects;
+    try {
+        projects = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        problems.push("projects.json is not valid JSON");
+        return { items, problems };
+    }
+    if (!Array.isArray(projects)) {
+        problems.push("projects.json is not a list");
+        return { items, problems };
+    }
+    const texts = [];
+    for (const raw of projects) {
+        const name = typeof raw?.name === "string" ? raw.name : "untitled";
+        const parts = [
+            `# ${name}`,
+            typeof raw.description === "string" ? raw.description : "",
+            typeof raw.prompt_template === "string"
+                ? `## Instructions\n\n${raw.prompt_template}`
+                : "",
+        ].filter(Boolean);
+        texts.push({
+            label: `claude.ai project ${name}`,
+            text: parts.join("\n\n"),
+            name,
+        });
+        for (const doc of Array.isArray(raw.docs) ? raw.docs : [])
+            if (typeof doc?.content === "string" && doc.content.trim()) {
+                const pieces = splitMarkdown(doc.content);
+                pieces.forEach((piece, index) => {
+                    texts.push({
+                        label: `claude.ai project ${name} doc ${String(doc.filename ?? "")}${pieces.length > 1 ? `#${index + 1}` : ""}`,
+                        text: piece,
+                        name,
+                    });
+                });
+            }
+    }
+    return { items: await proposeImported(texts, options), problems };
+}
+// Texts read from a provider (an export, or what a cache kept of its pages) → candidates, each
+// proposed once: the ledger remembers every text, also across spacing and case.
+export async function proposeImported(texts, options = {}) {
+    const items = [];
+    const ledger = await readLedger();
+    const seen = new Set();
+    for (const { label, text, name, source = "claude.ai" } of texts) {
+        const keys = [sha256(text), normalizedKey(text)];
+        const placed = placementMeta({ client: source, file: label, text }, options.classify?.({ client: source, file: label, text, name }) ?? {});
+        const item = {
+            source,
+            file: label,
+            bytes: Buffer.byteLength(text, "utf8"),
+            status: keys.some((key) => ledger[key] || seen.has(key))
+                ? "seen"
+                : Buffer.byteLength(text, "utf8") > MAX_BYTES
+                    ? "too-large"
+                    : "new",
+            project: placed.project,
+            title: placed.title,
+        };
+        for (const key of keys)
+            seen.add(key);
+        if (item.status === "new" && options.apply)
+            try {
+                const proposed = await proposeMemory({
+                    content: text,
+                    origin: "imported",
+                    source,
+                    reason: label.slice(0, 200),
+                    target: placed.target,
+                    meta: placed.meta,
+                });
+                for (const key of keys)
+                    ledger[key] = proposed.candidate;
+                item.status = "proposed";
+                item.candidate = proposed.candidate;
+            }
+            catch (error) {
+                if (!(error instanceof MemoryContractError))
+                    throw error;
+                item.status = error.code === "SECRET" ? "secret" : "too-large";
+            }
+        items.push(item);
+    }
+    if (options.apply) {
+        await mkdir(path.dirname(ledgerFile()), { recursive: true, mode: 0o700 });
+        await writeFile(ledgerFile(), `${JSON.stringify(ledger, null, 2)}\n`, {
+            mode: 0o600,
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=memory-harvest.js.map

package/node_modules/@ocean/brain/dist/memory/memory-paths.js

@@ -0,0 +1,174 @@
+import { lstatSync } from "node:fs";
+import path from "node:path";
+import { MemoryContractError } from "@ocean/core/domain/mcp/memory-contract.js";
+import { INBOX_DIR, oceanPath, PERSONAL_DIR, PROJECTS_DIR, projectDir, projectPathParts, resolveWithin, SYSTEM_DIR, } from "@ocean/core/shared/paths.js";
+// Every place the memory tools may write, and nothing else (T-296). Permanent records are the
+// only paths a caller chooses; candidates, versions, trash, the audit log and the client
+// journal are named by the server. Native staging belongs to a client's own memory feature.
+// Indexes and the conflicts list are maintained by Ocean itself, never written as records.
+const PROTECTED = new Set([
+    "memory.md",
+    "knowledge.md",
+    "projects.md",
+    "conflicts.md",
+    "inbox.md",
+]);
+const clientIdPattern = /^[a-z0-9][a-z0-9-]{0,40}$/;
+function workspaceRelative(file) {
+    return path.relative(oceanPath(), file).split(path.sep).join("/");
+}
+// A symlink anywhere from the root down, or a hard-linked target, could make a write land in a
+// file outside the record the caller named; resolveWithin alone accepts in-root symlinks.
+export function assertNoLinks(root, file) {
+    const resolvedRoot = path.resolve(root);
+    const parts = path.relative(resolvedRoot, path.resolve(file)).split(path.sep);
+    let current = resolvedRoot;
+    for (const part of ["", ...parts]) {
+        current = part ? path.join(current, part) : current;
+        let stats;
+        try {
+            stats = lstatSync(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (stats.isSymbolicLink())
+            throw new MemoryContractError("SYMLINK", `${workspaceRelative(current)} is a symbolic link`);
+        if (current === path.resolve(file) && stats.isFile() && stats.nlink > 1)
+            throw new MemoryContractError("HARDLINK", `${workspaceRelative(current)} has more than one hard link`);
+    }
+}
+function segments(relative) {
+    if (typeof relative !== "string" ||
+        !relative ||
+        relative.includes("\0") ||
+        path.isAbsolute(relative) ||
+        /^[A-Za-z]:/.test(relative))
+        throw new MemoryContractError("OUT_OF_ROOT", "path must be a relative path inside the workspace");
+    const parts = relative.split(/[\\/]/);
+    if (parts.some((part) => part === "" || part === "." || part === ".."))
+        throw new MemoryContractError("OUT_OF_ROOT", "path must not contain empty, '.' or '..' segments");
+    if (parts.some((part) => part.startsWith(".")))
+        throw new MemoryContractError("OUT_OF_ROOT", "path must not contain hidden segments");
+    return parts;
+}
+// A permanent record: `02-personal/**/*.md` or `04-projects/<id>/memory/**/*.md`.
+export function permanentRecord(relative) {
+    const parts = segments(relative);
+    const name = parts.at(-1) ?? "";
+    if (!name.toLowerCase().endsWith(".md"))
+        throw new MemoryContractError("INVALID", "a record must be a .md file");
+    if (PROTECTED.has(name.toLowerCase()))
+        throw new MemoryContractError("PROTECTED", `${name} is maintained by Ocean, not written as a record`);
+    const joined = parts.join("/");
+    const under = (dir) => joined.startsWith(`${dir}/`)
+        ? joined.slice(dir.length + 1).split("/")
+        : null;
+    let root;
+    let rest;
+    const personal = under(PERSONAL_DIR);
+    const inProjects = under(PROJECTS_DIR);
+    const project = inProjects ? projectPathParts(inProjects) : null;
+    const [folder, ...inProject] = project?.rest ?? [];
+    if (personal) {
+        root = oceanPath(PERSONAL_DIR);
+        rest = personal;
+    }
+    else if (project && folder === "memory" && inProject.length) {
+        root = oceanPath(projectDir(project.id), "memory");
+        rest = inProject;
+    }
+    else
+        throw new MemoryContractError("OUT_OF_ROOT", `records live under ${PERSONAL_DIR}/ or ${PROJECTS_DIR}/[<category>/]<project>/memory/`);
+    let file;
+    try {
+        file = resolveWithin(root, ...rest);
+    }
+    catch {
+        throw new MemoryContractError("OUT_OF_ROOT", "path escapes its root");
+    }
+    assertNoLinks(root, file);
+    return {
+        file,
+        relative: workspaceRelative(file),
+        root,
+        personal: Boolean(personal),
+    };
+}
+// A project doc, `04-projects/<id>/docs/**/*.md` (T-307): written only as a new file, by an
+// approved or auto-filed candidate — never through memory_write, so a doc the owner wrote is
+// never changed or removed by a client.
+export function projectDocument(relative) {
+    const parts = segments(relative);
+    const name = parts.at(-1) ?? "";
+    if (!name.toLowerCase().endsWith(".md"))
+        throw new MemoryContractError("INVALID", "a doc must be a .md file");
+    const joined = parts.join("/");
+    const project = joined.startsWith(`${PROJECTS_DIR}/`)
+        ? projectPathParts(joined.slice(PROJECTS_DIR.length + 1).split("/"))
+        : null;
+    const [folder, ...inside] = project?.rest ?? [];
+    if (!project || folder !== "docs" || !inside.length)
+        throw new MemoryContractError("OUT_OF_ROOT", `docs live under ${PROJECTS_DIR}/[<category>/]<project>/docs/`);
+    const root = oceanPath(projectDir(project.id), "docs");
+    let file;
+    try {
+        file = resolveWithin(root, ...inside);
+    }
+    catch {
+        throw new MemoryContractError("OUT_OF_ROOT", "path escapes its root");
+    }
+    assertNoLinks(root, file);
+    return { file, relative: workspaceRelative(file), root, personal: false };
+}
+function stateDir(...parts) {
+    return oceanPath(SYSTEM_DIR, "state", ...parts);
+}
+export function candidatesRoot() {
+    return oceanPath(INBOX_DIR, "candidates");
+}
+// Server-named only: <candidates>/<yyyy-mm-dd>/<id>.md.
+export function candidateFile(day, id) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !/^[0-9a-z-]{8,64}$/.test(id))
+        throw new MemoryContractError("INVALID", "bad candidate name");
+    const root = candidatesRoot();
+    const file = resolveWithin(root, day, `${id}.md`);
+    assertNoLinks(root, file);
+    return file;
+}
+// Where a client's own memory feature is redirected to (e.g. Claude Code's
+// autoMemoryDirectory). Ocean only reads it, to turn its files into candidates.
+export function stagingDir(client) {
+    if (!clientIdPattern.test(client))
+        throw new MemoryContractError("INVALID", `bad client id '${client}'`);
+    return resolveWithin(oceanPath(INBOX_DIR, "native"), client);
+}
+export function versionsRoot() {
+    return stateDir("memory", "versions");
+}
+export function trashRoot() {
+    return stateDir("memory", "trash");
+}
+// A stored copy of a record: <versions|trash>/<id>/<workspace-relative path>.
+export function storedCopy(kind, id, relative) {
+    const root = kind === "versions" ? versionsRoot() : trashRoot();
+    if (!/^[0-9a-z-]{8,64}$/.test(id))
+        throw new MemoryContractError("INVALID", "bad stored copy id");
+    const file = resolveWithin(root, id, ...segments(relative));
+    assertNoLinks(root, file);
+    return file;
+}
+// Content hashes of harvested native-memory texts → their candidate (T-296 P4).
+export function harvestLedgerFile() {
+    return stateDir("memory", "harvest.json");
+}
+export function auditFile() {
+    return stateDir("memory", "audit.jsonl");
+}
+// The client-configuration journal (P2): only Ocean-managed values, never whole client files.
+export function clientJournalFile() {
+    return stateDir("clients", "journal.jsonl");
+}
+//# sourceMappingURL=memory-paths.js.map