hippo-memory 1.60.0 → 1.62.0

package/dist/hooks/shared.js

@@ -0,0 +1,77 @@
+import { envHomeDir, processEnv } from '../env.js';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** JSON-value string check. `constructor` narrows a primitive via its boxed wrapper
+ *  instead of inspecting the `typeof` tag (anti-slop/no-runtime-typeof); equivalent to
+ *  `typeof value === 'string'` for every value JSON.parse can ever produce. */
+export function isJsonString(value) {
+    return value !== undefined && value !== null && value.constructor === String;
+}
+/** JSON-value plain-object check (excludes arrays and null), typeof-free for the same
+ *  reason as isJsonString above. */
+export function isJsonObject(value) {
+    return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
+}
+export const HIPPO_SLEEP_MARKER = 'hippo sleep';
+export const HIPPO_LAST_SLEEP_MARKER = 'hippo last-sleep';
+export const HIPPO_CAPTURE_MARKER = 'hippo capture --last-session';
+export const HIPPO_SESSION_END_MARKER = 'hippo session-end';
+export const HIPPO_PINNED_INJECT_MARKER = 'hippo context --pinned-only';
+export const HIPPO_PINNED_INJECT_COMMAND = 'hippo context --pinned-only --include-recent 5 --format additional-context';
+export const HIPPO_CODEX_WRAPPER_MARKER = 'hippo codex wrapper';
+export const HIPPO_PRE_COMPACT_MARKER = 'hippo pre-compact';
+export const HIPPO_COMPACT_RESUME_MARKER = 'hippo compact-resume';
+export const HIPPO_CAPTURE_ERROR_MARKER = 'hippo capture-error';
+export const HIPPO_POST_COMPACT_MARKER = 'hippo post-compact';
+export function homeDir() {
+    return envHomeDir() || os.homedir();
+}
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export function codexHomeDir(home = homeDir(), env = processEnv()) {
+    return env.CODEX_HOME || path.join(home, '.codex');
+}
+/** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
+export function isCodexPresent(home = homeDir()) {
+    return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
+}
+/** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
+export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+/**
+ * Default log path consumed by `hippo last-sleep`. Shared fallback when
+ * a caller doesn't pass --path explicitly.
+ */
+export function defaultSleepLogPath() {
+    return path.join(homeDir(), '.hippo', 'logs', 'last-sleep.log');
+}
+/**
+ * Diagnostic-only log path for `hippo pre-compact`. Deliberately separate
+ * from the SessionEnd sleep log: `hippo last-sleep` truncates that file on
+ * every SessionStart, which would wipe pre-compact lines before anyone
+ * could read them. Nothing consumes this file programmatically — it exists
+ * for manual troubleshooting only. Overridden by `--log-file`.
+ */
+export function defaultPreCompactLogPath() {
+    return path.join(homeDir(), '.hippo', 'logs', 'pre-compact.log');
+}
+export function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/**
+ * Detect which AI coding tools are installed based on config directory presence.
+ * Used by `hippo setup` to decide which JSON-hook installs to run.
+ */
+export function detectInstalledTools() {
+    const home = homeDir();
+    const exists = (...parts) => fs.existsSync(path.join(home, ...parts));
+    return [
+        { name: 'claude-code', configDir: '~/.claude', detected: exists('.claude'), kind: 'json-hook' },
+        { name: 'opencode', configDir: '~/.config/opencode', detected: exists('.config', 'opencode'), kind: 'plugin', notes: 'installs a TS plugin at ~/.config/opencode/plugins/hippo.ts' },
+        { name: 'openclaw', configDir: '~/.openclaw', detected: exists('.openclaw'), kind: 'plugin', notes: 'install via `openclaw plugins install hippo-memory`' },
+        { name: 'codex', configDir: '~/.codex', detected: isCodexPresent(home), kind: 'wrapper', notes: 'memory hooks in hooks.json, and wraps the detected codex launcher for session-end consolidation' },
+        { name: 'cursor', configDir: '~/.cursor', detected: exists('.cursor'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
+        { name: 'pi', configDir: '~/.pi', detected: exists('.pi'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
+    ];
+}
+//# sourceMappingURL=shared.js.map

package/dist/http-retry.d.ts

@@ -7,6 +7,8 @@ export interface RetryPolicy {
     baseDelayMs?: number;
     /** A Retry-After longer than this hands the response back, so a caller with its own long pause keeps it. */
     maxDelayMs?: number;
+    /** Which responses to retry; defaults to 429 and 5xx. A write narrows it to answers that prove nothing committed. */
+    retryOn?: (res: Response) => boolean;
     fetchFn?: typeof fetch;
     sleep?: (ms: number) => Promise<void>;
     random?: () => number;

package/dist/http-retry.js

@@ -1,12 +1,12 @@
 /** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+import { envLlmTimeoutMs } from './env.js';
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 250;
 const DEFAULT_MAX_DELAY_MS = 8_000;
 const DEFAULT_LLM_TIMEOUT_MS = 60_000;
 /** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
 export function llmTimeoutMs() {
-    const parsed = Number.parseInt(process.env.HIPPO_LLM_TIMEOUT_MS ?? '', 10);
-    return parsed > 0 ? parsed : DEFAULT_LLM_TIMEOUT_MS;
+    return envLlmTimeoutMs() ?? DEFAULT_LLM_TIMEOUT_MS;
 }
 export function isRetryableStatus(status) {
     return status === 429 || (status >= 500 && status <= 599);
@@ -30,11 +30,12 @@ export async function fetchWithRetry(url, init, policy) {
     const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
     const sleep = policy.sleep ?? realSleep;
     const random = policy.random ?? Math.random;
+    const retryOn = policy.retryOn ?? ((res) => isRetryableStatus(res.status));
     for (let attempt = 1;; attempt++) {
         const timeout = AbortSignal.timeout(policy.timeoutMs);
         const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
         const res = await fetchFn(url, { ...init, signal });
-        if (!isRetryableStatus(res.status) || attempt >= attempts)
+        if (!retryOn(res) || attempt >= attempts)
             return res;
         const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
         if (retryAfter !== null && retryAfter > maxDelayMs)

package/dist/http-util.d.ts

@@ -28,6 +28,9 @@ export declare function sendJson<T>(res: ServerResponse, status: number, body: T
  * mid-stream so we don't wait for an attacker to finish before erroring out.
  */
 export declare function readBody(req: IncomingMessage): Promise<string>;
+export declare const LOOPBACK_HOST_HEADER: RegExp;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export declare function isCrossSite(req: IncomingMessage): boolean;
 /** Per-request values a connector webhook receiver reads; ServeOpts and the /v1 RouteRequest both satisfy it. */
 export interface WebhookRequest {
     req: IncomingMessage;

package/dist/http-util.js

@@ -53,4 +53,14 @@ export async function readBody(req) {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
+// Any other Host on a loopback socket is DNS rebinding: a hostile page resolved to 127.0.0.1.
+export const LOOPBACK_HOST_HEADER = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export function isCrossSite(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return true;
+    const origin = req.headers.origin;
+    return origin !== undefined && origin !== `http://${req.headers.host}`;
+}
 //# sourceMappingURL=http-util.js.map

package/dist/{importers.d.ts → importers/core.d.ts}

@@ -2,7 +2,7 @@
  * Memory importers for Hippo.
  * Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown.
  */
-import { MemoryEntry } from './memory.js';
+import { MemoryEntry } from '../memory.js';
 export interface ImportResult {
     total: number;
     imported: number;
@@ -58,19 +58,15 @@ export interface ImportOptions {
  * create MemoryEntry objects, write them (unless dry-run), and return a result.
  */
 export declare function importEntries(chunks: string[], source: string, tags: string[], options: ImportOptions): ImportResult;
-export declare function importChatGPT(filePath: string, options: ImportOptions): ImportResult;
-export declare function importClaude(filePath: string, options: ImportOptions): ImportResult;
-/** Import `.cursorrules`, one rule file, or a `.cursor/rules` tree of `.mdc` and `.md` rules. */
-export declare function importCursor(sourcePath: string, options: ImportOptions): ImportResult;
-export declare function importGenericFile(filePath: string, options: ImportOptions): ImportResult;
-export declare function importMarkdown(filePath: string, options: ImportOptions): ImportResult;
-/**
- * Import a markdown vault FOLDER as `kind='raw'` memories.
- *
- * NOT re-entrant: idempotency rests on the in-memory `existing` Map loaded once
- * at the top. Two concurrent importVault runs over the same vault could both see
- * a note as absent and double-insert (the connector pattern relies on a single
- * sequential writer; same caveat applies here).
- */
-export declare function importVault(folderPath: string, options: ImportOptions): ImportResult;
-//# sourceMappingURL=importers.d.ts.map
+/** The full value space `JSON.parse` can produce. Boundary-guard functions in
+ *  this file accept `JsonValue` (never `unknown`) so a value's origin as
+ *  unparsed external JSON stays visible in its type, then narrow it via the
+ *  `isJson*` predicates below. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isJsonString(x: JsonValue): x is string;
+export declare function isJsonPlainObject(x: JsonValue): x is {
+    [key: string]: JsonValue;
+};
+//# sourceMappingURL=core.d.ts.map

package/dist/importers/core.js

@@ -0,0 +1,141 @@
+/**
+ * Memory importers for Hippo.
+ * Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown.
+ */
+import { createMemory, Layer } from '../memory.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { duplicateKey, storedTextKeys } from '../same-text.js';
+import { getGlobalRoot, initGlobal } from '../shared.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { RejectedValueError, checkRejectionGuard } from '../rejection.js';
+import { loadConfig } from '../config.js';
+import { vetSecrets } from '../secret-detect.js';
+import { log } from '../log.js';
+// ---------------------------------------------------------------------------
+// Shared core: dedup + write
+// ---------------------------------------------------------------------------
+/**
+ * Given an array of raw text chunks, deduplicate against existing memories,
+ * create MemoryEntry objects, write them (unless dry-run), and return a result.
+ */
+export function importEntries(chunks, source, tags, options) {
+    const targetRoot = options.global ? getGlobalRoot() : options.hippoRoot;
+    // Ensure store is ready
+    if (options.global) {
+        initGlobal();
+    }
+    const keys = storedTextKeys(loadAllEntries(targetRoot, options.global ? undefined : options.tenantId));
+    const allTags = [...new Set([...tags, ...(options.extraTags ?? [])])];
+    const baseHalfLifeDays = loadConfig(targetRoot).defaultHalfLifeDays;
+    let total = 0;
+    let imported = 0;
+    let skipped = 0;
+    let rejected = 0;
+    let redacted = 0;
+    const entries = [];
+    // AT1 P2 fix: a dry-run preview never called writeEntry, so it never
+    // checked tombstones either — every non-duplicate chunk counted as
+    // `imported` even when a real run would refuse it, making the preview's
+    // `rejected` count silently 0. Probe (read-only) via the same guard
+    // writeEntry uses internally, without ever writing.
+    const dryRunDb = options.dryRun ? openHippoDb(targetRoot) : null;
+    try {
+        for (const raw of chunks) {
+            const { chunk, wasRedacted } = prepareImportChunk(raw, allTags);
+            // Skip empty or too-short chunks
+            if (!chunk || chunk.length < 10) {
+                skipped++;
+                continue;
+            }
+            total++;
+            // Dedup check: skip only when the same text is already stored
+            if (keys.has(duplicateKey(chunk))) {
+                skipped++;
+                continue;
+            }
+            const entry = createImportEntry(chunk, source, allTags, options, baseHalfLifeDays);
+            if (!writeOrProbeImport(targetRoot, entry, options, dryRunDb)) {
+                rejected++;
+                continue;
+            }
+            // Add to existing so subsequent chunks dedup against freshly imported ones
+            if (!options.dryRun)
+                keys.add(duplicateKey(chunk));
+            entries.push(entry);
+            imported++;
+            if (wasRedacted)
+                redacted++;
+        }
+        return { total, imported, skipped, rejected, redacted, entries };
+    }
+    finally {
+        if (dryRunDb)
+            closeHippoDb(dryRunDb);
+    }
+}
+/** The secret-vetted chunk capped at 1000 chars, and whether vetting changed it. */
+function prepareImportChunk(raw, allTags) {
+    const original = raw.trim();
+    const trimmed = vetSecrets(original, allTags, true).content;
+    const wasRedacted = trimmed !== original;
+    if (trimmed.length > 1000) {
+        log.warn(`imported memory truncated from ${trimmed.length} to 1000 chars`);
+    }
+    return { chunk: trimmed.slice(0, 1000), wasRedacted };
+}
+function createImportEntry(chunk, source, allTags, options, baseHalfLifeDays) {
+    // A3: kind defaults to 'distilled'. ChatGPT/Claude/Cursor exports are curated
+    // user pastes, not raw transcripts from a system of record, so distilled is
+    // correct here. E1.3 (Slack ingestion) shipped 2026-04-29 in src/connectors/slack/
+    // and sets kind: 'raw' + routes deletions through archiveRawMemory() — these
+    // importers stay 'distilled' per the original reasoning. See MEMORY_ENVELOPE.md.
+    // L9: the dedup read above is scoped by options.tenantId — the WRITE
+    // must match, or scoped-dedup-passes-then-default-tenant-write breaks
+    // the per-tenant contract. Mirror the dedup-read guard: global=true
+    // → host-wide write to global store (tenantId irrelevant, createMemory
+    // defaults to 'default'). global=false → write to the same tenant as
+    // the dedup read.
+    return createMemory(chunk, {
+        layer: Layer.Episodic,
+        tags: allTags,
+        source,
+        confidence: 'observed',
+        tenantId: options.global ? undefined : options.tenantId,
+        baseHalfLifeDays,
+    });
+}
+/** Writes the entry, or on a dry run only probes the guard; false when a rejected value refuses it. */
+function writeOrProbeImport(targetRoot, entry, options, dryRunDb) {
+    if (options.dryRun) {
+        if (dryRunDb) {
+            try {
+                checkRejectionGuard(dryRunDb, entry.tenantId ?? 'default', entry.id, entry.content);
+            }
+            catch (err) {
+                if (err instanceof RejectedValueError)
+                    return false;
+                throw err;
+            }
+        }
+        return true;
+    }
+    // AT1 (plan §3 containment): a rejection refuses one CHUNK, not the
+    // whole import batch. Caught per-item so siblings still land.
+    try {
+        writeEntry(targetRoot, entry);
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError)
+            return false;
+        throw err;
+    }
+    return true;
+}
+export function isJsonString(x) {
+    return typeof x === 'string';
+}
+export function isJsonPlainObject(x) {
+    return x !== null && !Array.isArray(x) && typeof x === 'object';
+}
+//# sourceMappingURL=core.js.map

package/dist/importers/markdown-parse.d.ts

@@ -0,0 +1,41 @@
+/** Minimal inline frontmatter split. Recognises a leading `---\n…\n---\n`
+ *  block (no YAML dep). Returns the parsed key→value map plus the body with the
+ *  block removed. When no well-formed block is present, `fm` is empty and
+ *  `body` is the original content. */
+interface FrontmatterParseResult {
+    fm: Record<string, string>;
+    body: string;
+}
+export declare function parseFrontmatter(raw: string): FrontmatterParseResult;
+/** Pull a frontmatter field that may be a YAML flow list (`[a, b]`), a
+ *  comma-separated scalar (`a, b`), or a single token, into a string[]. Quotes
+ *  and surrounding brackets are stripped; empty entries dropped. */
+export declare function frontmatterList(value: string | undefined): string[];
+/** Parse `[[wikilinks]]` from body text. `[[target]]` and `[[target|alias]]`
+ *  both yield `target` (alias dropped). Returns de-duplicated, order-preserving
+ *  target strings (trimmed). Embeds (`![[…]]`) are intentionally matched too —
+ *  the leading `!` is not part of the `[[…]]` capture, so an embed contributes
+ *  its target as a candidate, which is the desired no-crash baseline behaviour. */
+export declare function parseWikilinks(body: string): string[];
+/** Recursively collect files whose name matches `match` (`*.md` by default) under `root`,
+ *  as paths relative to `root` with forward-slash separators (stable artifactRef keys across OSes).
+ *  Symlinks are not followed. Skips dot-directories (the default `.hippo` store,
+ *  `.git`, `.obsidian`, `.trash`) AND the canonicalized Hippo store path during
+ *  the walk, so re-importing a vault that CONTAINS the store never ingests its own
+ *  markdown mirror files (codex R5 P1: `hippo import --vault .` after `hippo
+ *  init` in the vault would otherwise self-import its mirror rows and grow on
+ *  every run). The root-IS-the-store case is handled one level up in
+ *  importVault (a no-op early return), NOT here: returning [] for it would feed
+ *  the deletion-sync an empty scan that mass-archives every live row (codex R8). */
+export declare function collectMarkdownFiles(root: string, hippoRoot: string, match?: RegExp): string[];
+/** Canonicalize a path for the self-store comparison: dereference symlinks /
+ *  junctions and normalize case (Windows) via the OS realpath, so a junction or
+ *  a case-variant path to the store is still recognized as self-store (codex R9
+ *  P2: path.resolve does neither, so an aliased store path slipped past the
+ *  guard and triggered the mass-archive). Falls back to path.resolve when the
+ *  path does not exist yet - an uninitialized store or a typo'd vault path
+ *  cannot be a live self-store, and a non-existent vault folder fails later in
+ *  the walk (readdirSync) before deletion-sync can archive anything. */
+export declare function realpathOrResolve(p: string): string;
+export {};
+//# sourceMappingURL=markdown-parse.d.ts.map

package/dist/importers/markdown-parse.js

@@ -0,0 +1,132 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { log } from '../log.js';
+export function parseFrontmatter(raw) {
+    // Must start with `---` on its own line. Accept CRLF or LF.
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!m)
+        return { fm: {}, body: raw };
+    const block = m[1];
+    const body = raw.slice(m[0].length);
+    const fm = {};
+    const lines = block.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const kv = lines[i].match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (!kv)
+            continue;
+        let val = kv[2].trim();
+        if (val === '') {
+            // YAML block-style list: `key:` followed by indented `- item` lines
+            // (common in Obsidian/Dendron frontmatter). Collect them into a
+            // comma-joined value so frontmatterList parses them (codex P2).
+            const items = [];
+            let j = i + 1;
+            let item;
+            while (j < lines.length && (item = lines[j].match(/^\s+-\s+(.+?)\s*$/)) !== null) {
+                items.push(item[1].replace(/^['"]|['"]$/g, '').trim());
+                j++;
+            }
+            if (items.length) {
+                val = items.join(', ');
+                i = j - 1;
+            }
+        }
+        fm[kv[1]] = val;
+    }
+    return { fm, body };
+}
+/** Pull a frontmatter field that may be a YAML flow list (`[a, b]`), a
+ *  comma-separated scalar (`a, b`), or a single token, into a string[]. Quotes
+ *  and surrounding brackets are stripped; empty entries dropped. */
+export function frontmatterList(value) {
+    if (!value)
+        return [];
+    let v = value.trim();
+    if (v.startsWith('[') && v.endsWith(']'))
+        v = v.slice(1, -1);
+    return v
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, '').trim())
+        .filter(Boolean);
+}
+/** Parse `[[wikilinks]]` from body text. `[[target]]` and `[[target|alias]]`
+ *  both yield `target` (alias dropped). Returns de-duplicated, order-preserving
+ *  target strings (trimmed). Embeds (`![[…]]`) are intentionally matched too —
+ *  the leading `!` is not part of the `[[…]]` capture, so an embed contributes
+ *  its target as a candidate, which is the desired no-crash baseline behaviour. */
+export function parseWikilinks(body) {
+    const out = [];
+    const seen = new Set();
+    const re = /\[\[([^\]]+?)\]\]/g;
+    let match;
+    while ((match = re.exec(body)) !== null) {
+        const inner = match[1];
+        const target = (inner.split('|')[0] ?? '').trim();
+        if (!target)
+            continue;
+        if (seen.has(target))
+            continue;
+        seen.add(target);
+        out.push(target);
+    }
+    return out;
+}
+/** Recursively collect files whose name matches `match` (`*.md` by default) under `root`,
+ *  as paths relative to `root` with forward-slash separators (stable artifactRef keys across OSes).
+ *  Symlinks are not followed. Skips dot-directories (the default `.hippo` store,
+ *  `.git`, `.obsidian`, `.trash`) AND the canonicalized Hippo store path during
+ *  the walk, so re-importing a vault that CONTAINS the store never ingests its own
+ *  markdown mirror files (codex R5 P1: `hippo import --vault .` after `hippo
+ *  init` in the vault would otherwise self-import its mirror rows and grow on
+ *  every run). The root-IS-the-store case is handled one level up in
+ *  importVault (a no-op early return), NOT here: returning [] for it would feed
+ *  the deletion-sync an empty scan that mass-archives every live row (codex R8). */
+export function collectMarkdownFiles(root, hippoRoot, match = /\.md$/i) {
+    const out = [];
+    // Canonicalize (realpath) so a non-dot HIPPO_HOME store nested in the vault is
+    // skipped even when hippoRoot is an aliased path (junction / Windows case
+    // variant); path.resolve would miss it and self-import the store's mirror
+    // files (codex R9 follow-up: same gap as the importVault guard, sibling site).
+    const resolvedHippoRoot = realpathOrResolve(hippoRoot);
+    const walk = (dir) => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const ent of entries) {
+            if (ent.isSymbolicLink())
+                continue;
+            const abs = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                // Skip dot-dirs (config/system, incl. the default `.hippo` store) and
+                // the canonicalized store path (covers a HIPPO_HOME outside `.hippo`).
+                if (ent.name.startsWith('.'))
+                    continue;
+                if (realpathOrResolve(abs) === resolvedHippoRoot)
+                    continue;
+                walk(abs);
+            }
+            else if (ent.isFile() && match.test(ent.name)) {
+                out.push(path.relative(root, abs).split(path.sep).join('/'));
+            }
+        }
+    };
+    walk(root);
+    out.sort();
+    return out;
+}
+/** Canonicalize a path for the self-store comparison: dereference symlinks /
+ *  junctions and normalize case (Windows) via the OS realpath, so a junction or
+ *  a case-variant path to the store is still recognized as self-store (codex R9
+ *  P2: path.resolve does neither, so an aliased store path slipped past the
+ *  guard and triggered the mass-archive). Falls back to path.resolve when the
+ *  path does not exist yet - an uninitialized store or a typo'd vault path
+ *  cannot be a live self-store, and a non-existent vault folder fails later in
+ *  the walk (readdirSync) before deletion-sync can archive anything. */
+export function realpathOrResolve(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch (err) {
+        log.debug(`import: realpath fell back to resolve for ${p}: ${err instanceof Error ? err.message : String(err)}`);
+        return path.resolve(p);
+    }
+}
+//# sourceMappingURL=markdown-parse.js.map

package/dist/importers/markdown.d.ts

@@ -0,0 +1,3 @@
+import { type ImportResult, type ImportOptions } from './core.js';
+export declare function importMarkdown(filePath: string, options: ImportOptions): ImportResult;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/importers/markdown.js

@@ -0,0 +1,92 @@
+import * as fs from 'fs';
+import { importEntries } from './core.js';
+// ---------------------------------------------------------------------------
+// Structured markdown importer (MEMORY.md / AGENTS.md format)
+// ---------------------------------------------------------------------------
+/**
+ * Slugify a heading for use as a tag.
+ * "Data Pipeline & Cache" -> "data-pipeline-cache"
+ */
+function slugify(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 50);
+}
+/**
+ * Parse structured markdown into {content, sectionSlug} pairs.
+ * Each heading starts a new section. Bullet points / numbered items under
+ * the heading become individual memories tagged with the section slug.
+ */
+function parseStructuredMarkdown(raw) {
+    const results = [];
+    const lines = raw.split('\n');
+    let currentSection = '';
+    let currentSlug = '';
+    let pendingText = '';
+    function flush() {
+        if (!pendingText.trim())
+            return;
+        results.push({ content: pendingText.trim(), sectionSlug: currentSlug });
+        pendingText = '';
+    }
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Heading
+        const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)/);
+        if (headingMatch) {
+            flush();
+            currentSection = headingMatch[2].trim();
+            currentSlug = slugify(currentSection);
+            continue;
+        }
+        // Bullet or numbered item: flush previous, start new
+        if (/^[-*+]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed)) {
+            flush();
+            const itemText = trimmed.replace(/^[-*+]\s+/, '').replace(/^\d+\.\s+/, '').trim();
+            pendingText = itemText;
+            continue;
+        }
+        // Empty line: flush current pending
+        if (!trimmed) {
+            flush();
+            continue;
+        }
+        // Continuation of current item
+        pendingText = pendingText ? pendingText + ' ' + trimmed : trimmed;
+    }
+    flush();
+    return results.filter((r) => r.content.length > 0);
+}
+export function importMarkdown(filePath, options) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = parseStructuredMarkdown(raw);
+    // Group by section slug so we can pass per-chunk tags
+    // We call importEntries per unique slug to get the right tags per section
+    const bySlug = new Map();
+    for (const { content, sectionSlug } of parsed) {
+        const list = bySlug.get(sectionSlug) ?? [];
+        list.push(content);
+        bySlug.set(sectionSlug, list);
+    }
+    let totalResult = { total: 0, imported: 0, skipped: 0, rejected: 0, entries: [] };
+    for (const [slug, chunks] of bySlug.entries()) {
+        const sectionTags = slug ? ['imported', slug] : ['imported'];
+        const result = importEntries(chunks, 'import:markdown', sectionTags, options);
+        totalResult = {
+            total: totalResult.total + result.total,
+            imported: totalResult.imported + result.imported,
+            skipped: totalResult.skipped + result.skipped,
+            // AT1 P2 fix: `rejected` is now optional on ImportResult (compat) — tolerate
+            // undefined on either side of the accumulation.
+            rejected: (totalResult.rejected ?? 0) + (result.rejected ?? 0),
+            redacted: (totalResult.redacted ?? 0) + (result.redacted ?? 0),
+            entries: [...totalResult.entries, ...result.entries],
+        };
+    }
+    return totalResult;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/importers/sources.d.ts

@@ -0,0 +1,7 @@
+import { type ImportResult, type ImportOptions } from './core.js';
+export declare function importChatGPT(filePath: string, options: ImportOptions): ImportResult;
+export declare function importClaude(filePath: string, options: ImportOptions): ImportResult;
+/** Import `.cursorrules`, one rule file, or a `.cursor/rules` tree of `.mdc` and `.md` rules. */
+export declare function importCursor(sourcePath: string, options: ImportOptions): ImportResult;
+export declare function importGenericFile(filePath: string, options: ImportOptions): ImportResult;
+//# sourceMappingURL=sources.d.ts.map