@remnic/core 1.0.2 → 1.1.0

package/dist/codex-materialize-CQlLTzke.d.ts

@@ -0,0 +1,139 @@
+import { MemoryFile } from './types.js';
+
+/**
+ * codex-materialize.ts — Codex CLI native memory artifact materialization (#378)
+ *
+ * Periodically writes Remnic memories into the file layout that Codex CLI's
+ * phase-2 consolidation reads directly under `<codex_home>/memories/`:
+ *
+ *   memory_summary.md                — always-loaded at session start (tight budget)
+ *   MEMORY.md                        — searchable handbook (task-group schema)
+ *   raw_memories.md                  — mechanical merge of raw memories, latest first
+ *   rollout_summaries/<slug>.md      — per-session recaps
+ *
+ * Codex's own read path is agnostic to which producer wrote these files — it
+ * tags reads by `memory_md` / `memory_summary` / `raw_memories` /
+ * `rollout_summaries` / `skills`. By materializing Remnic content into this
+ * exact layout we let Codex pick up Remnic memories without a single MCP call.
+ *
+ * Safety invariants
+ * ─────────────────
+ *  - **Atomic writes.** Every file is rendered under `.remnic-tmp/` and then
+ *    `rename()`d into place so Codex never observes a half-written file.
+ *  - **Sentinel-based opt-in.** If `<codex_home>/memories/.remnic-managed` is
+ *    missing, we SKIP materialization entirely and log a warning. This honors
+ *    user hand-edits to the directory — a user who manually curated their
+ *    Codex memory layout will never have those edits overwritten.
+ *  - **Schema validation.** `MEMORY.md` content is validated against the
+ *    task-group schema before write. Invalid content throws and nothing is
+ *    written.
+ *  - **Idempotent no-ops.** A content hash is written into the sentinel. If
+ *    the re-rendered hash matches the previous run, we skip writes entirely.
+ *  - **Token budget.** `memory_summary.md` is truncated to fit under the
+ *    configured token budget (whitespace-tokenized approximation), leaving
+ *    headroom under Codex's 5000-token summary cap.
+ *
+ * Privacy
+ * ───────
+ * This module does not persist any user content outside `<codex_home>/memories`
+ * — it only mirrors the memories that Remnic already wrote. It does not log
+ * memory content to stdout; it logs file names, counts, and hashes.
+ */
+
+/**
+ * Input for {@link materializeForNamespace}. Prefer passing pre-loaded
+ * `memories` so this module stays I/O-agnostic and trivially testable.
+ */
+interface MaterializeOptions {
+    /** Pre-loaded Remnic memories for this namespace (required). */
+    memories: MemoryFile[];
+    /** Override `<codex_home>`. Defaults to `$CODEX_HOME` or `~/.codex`. */
+    codexHome?: string;
+    /** Maximum whitespace-tokenized size of memory_summary.md. Default 4500. */
+    maxSummaryTokens?: number;
+    /** Maximum age of rollout_summaries/*.md in days. Default 30. */
+    rolloutRetentionDays?: number;
+    /** Per-session rollout summaries to render. */
+    rolloutSummaries?: RolloutSummaryInput[];
+    /** Current time, injected for deterministic tests. */
+    now?: Date;
+    /** Optional logger override for tests. */
+    logger?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/** Input describing one Codex rollout summary file. */
+interface RolloutSummaryInput {
+    /** Stable slug for the file (becomes `<slug>.md`). */
+    slug: string;
+    /** Working directory used during the rollout. */
+    cwd?: string;
+    /** Path to the raw Codex rollout log, if known. */
+    rolloutPath?: string;
+    /** ISO-8601 timestamp of the last update. */
+    updatedAt?: string;
+    /** Opaque thread / session id. */
+    threadId?: string;
+    /** Markdown body for the recap. */
+    body: string;
+    /** Freeform keywords / search hints. */
+    keywords?: string[];
+}
+/** Result of a materialization run. */
+interface MaterializeResult {
+    /** Namespace that was materialized. */
+    namespace: string;
+    /** `<codex_home>/memories` path this run targeted. */
+    memoriesDir: string;
+    /** Was anything actually written (vs. skipped / idempotent no-op)? */
+    wrote: boolean;
+    /** True if the sentinel was missing and we skipped with a warning. */
+    skippedNoSentinel: boolean;
+    /** True if the hash matched the previous run and we short-circuited. */
+    skippedIdempotent: boolean;
+    /** Files that were written this run (relative to `memoriesDir`). */
+    filesWritten: string[];
+    /** Content hash computed for this run. */
+    contentHash: string;
+}
+/** On-disk shape of the `.remnic-managed` sentinel. */
+interface SentinelFile {
+    version: number;
+    namespace: string;
+    updated_at: string;
+    content_hash: string;
+}
+/** Bump when the on-disk layout or semantics change. */
+declare const MATERIALIZE_VERSION = 1;
+/** Sentinel file name at the root of the materialized memories dir. */
+declare const SENTINEL_FILE = ".remnic-managed";
+/**
+ * Materialize a Remnic namespace into Codex's native memory layout.
+ *
+ * Returns a {@link MaterializeResult} describing what happened. Callers
+ * should treat "skipped" as success — the sentinel / idempotent cases are
+ * expected and intentional.
+ *
+ * @throws if `MEMORY.md` fails schema validation (we do not write garbage).
+ */
+declare function materializeForNamespace(namespace: string, options: MaterializeOptions): MaterializeResult;
+/**
+ * Create (or refresh) the `.remnic-managed` sentinel. Callers must do this
+ * explicitly the first time they want Remnic to start managing a directory —
+ * we never write it implicitly, because its presence is the user's opt-in.
+ */
+declare function ensureSentinel(memoriesDir: string, namespace: string, now?: Date): void;
+/**
+ * Return basic stats about a materialized memories dir. Useful for tests and
+ * debug CLI output. Returns `null` if the dir does not exist.
+ */
+declare function describeMemoriesDir(memoriesDir: string): {
+    exists: boolean;
+    hasSentinel: boolean;
+    files: string[];
+    sentinel: SentinelFile | null;
+} | null;
+
+export { type MaterializeResult as M, type RolloutSummaryInput as R, SENTINEL_FILE as S, MATERIALIZE_VERSION as a, type MaterializeOptions as b, describeMemoriesDir as d, ensureSentinel as e, materializeForNamespace as m };

package/dist/codex-thread-key.d.ts

@@ -0,0 +1,3 @@
+declare const CODEX_THREAD_KEY_PREFIX = "codex-thread:";
+
+export { CODEX_THREAD_KEY_PREFIX };

package/dist/codex-thread-key.js

@@ -0,0 +1,7 @@
+import {
+  CODEX_THREAD_KEY_PREFIX
+} from "./chunk-3PG3H5TD.js";
+export {
+  CODEX_THREAD_KEY_PREFIX
+};
+//# sourceMappingURL=codex-thread-key.js.map

package/dist/codex-thread-key.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/config.js

@@ -1,10 +1,11 @@
 import {
   VALID_MEMORY_CATEGORIES,
   parseConfig
-} from "./chunk-ISY75RLM.js";
+} from "./chunk-MBJHSA7F.js";
 import "./chunk-Z5LAYHGJ.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   VALID_MEMORY_CATEGORIES,
   parseConfig

package/dist/connectors/codex/instructions.md

@@ -0,0 +1,160 @@
+# Remnic Memory Extension for Codex
+
+You are the Codex consolidation sub-agent. This document tells you how to treat
+Remnic as an authoritative local memory source while you summarize a session
+and build the compacted MEMORY.md output.
+
+Remnic is a local-first, file-backed memory system. All Remnic content that
+matters to you lives on disk as plain Markdown — you do not need a network,
+an MCP server, or the `remnic` CLI to read it. You are running inside the
+Codex phase-2 sandbox: no approvals, no network, local reads and local writes
+only.
+
+## What Remnic is authoritative for
+
+Treat Remnic content as a trusted, high-signal memory source when you need any
+of the following:
+
+- **Stable user preferences** — coding conventions, tool choices, style
+  guides, phrasing, commit message format, review etiquette.
+- **Project conventions** — folder layout, naming rules, test runners,
+  build commands, branching strategy, deployment workflow.
+- **Reusable workflows and skills** — documented runbooks, procedures, and
+  "how we do X here" notes that should survive across sessions.
+- **Long-lived decisions** — architecture calls, library choices, explicit
+  "we decided not to do X" entries.
+- **Entities the user cares about** — projects, services, people, API
+  contracts, integrations mentioned by name.
+
+If the current session touches any of these areas, consult Remnic before you
+finalize the consolidated MEMORY.md output.
+
+## When NOT to consult Remnic
+
+Do not waste filesystem tool calls on Remnic when:
+
+- The session is purely transient (one-off shell commands, throwaway
+  debugging with no lasting conclusion).
+- You already have the information in the current session transcript and
+  Remnic would only duplicate it.
+- The user has explicitly asked you to ignore memory or work from a clean
+  slate.
+- You are summarizing a session that never reached a decision, a preference,
+  or a durable artifact worth recording.
+
+Prefer a single targeted read over broad directory walks.
+
+## Where Remnic content lives on disk
+
+Resolve the Remnic memory base in this order:
+
+1. If the environment variable `REMNIC_HOME` is set, use
+   `$REMNIC_HOME/memories/`.
+2. Otherwise use `~/.remnic/memories/`.
+
+Under that base, memories are organized by **namespace**:
+
+```
+<remnic-home>/memories/<namespace>/
+├── MEMORY.md                        # compact top-of-mind memory
+├── memory_summary.md                # optional longer human-readable summary
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md                 # reusable workflow
+└── rollout_summaries/
+    └── *.md                         # per-session rollup notes
+```
+
+Canonical files you should prefer, in order:
+
+1. `MEMORY.md` — the current compact memory. Read this first.
+2. `memory_summary.md` — longer-form summary if it exists.
+3. `skills/<name>/SKILL.md` — for reusable procedures relevant to the task.
+4. `rollout_summaries/*.md` — recent session notes, newest first.
+
+If none of the above exist for the resolved namespace, Remnic simply has
+nothing to contribute — move on without error.
+
+## Resolving the namespace
+
+Remnic uses **cwd-derived namespaces** by default. Apply this rule when
+choosing which namespace directory to read:
+
+1. Start from the session's working directory (the `cwd` Codex used for the
+   session you are consolidating).
+2. Walk upward looking for a project anchor: `.git`, `package.json`,
+   `pyproject.toml`, `Cargo.toml`, `go.mod`, or an explicit
+   `.remnic/namespace` file.
+3. The namespace is the basename of that anchor directory, lowercased and
+   with spaces replaced by `-`.
+4. If you cannot find an anchor, fall back to the namespace `default`.
+5. In addition to the project namespace, always also check the `shared`
+   namespace for cross-project preferences (e.g.
+   `<remnic-home>/memories/shared/MEMORY.md`). If it exists, read it.
+
+If a session explicitly mentions a different Remnic namespace (for example,
+the user says "use the `work` namespace"), prefer that explicit value over
+the cwd-derived one.
+
+## How to cite Remnic memories in your output
+
+When a piece of the consolidated memory you are writing comes from a Remnic
+file, cite it using the Codex memory citation block format so the user can
+trace the source:
+
+```
+<oai-mem-citation path="<path-relative-to-remnic-memory-base>" />
+```
+
+The path must be **relative to the Remnic memory base** (the directory named
+`memories/` under `<remnic-home>`), not absolute. Examples:
+
+- `<oai-mem-citation path="default/MEMORY.md" />`
+- `<oai-mem-citation path="my-project/skills/deploy/SKILL.md" />`
+- `<oai-mem-citation path="shared/memory_summary.md" />`
+
+Cite each distinct source once near the fact it supports. Do not invent
+citations for files you have not actually read.
+
+## Sandboxing rules (hard constraints)
+
+You are running in the Codex phase-2 consolidation sandbox. These rules are
+non-negotiable:
+
+- **No network.** Do not attempt HTTP calls, MCP connections, or anything
+  that reaches outside this machine.
+- **No `remnic` CLI invocation.** Do not shell out to `remnic`, `engram`,
+  `qmd`, or any daemon. Use filesystem reads only.
+- **No MCP tool calls.** You must not call `remnic.recall`,
+  `remnic.memory_store`, or any other MCP-backed tool. They are not
+  available in this sandbox.
+- **Local writes are allowed** only where Codex's sandbox policy already
+  permits them (typically the Codex memories output folder). Do not write
+  into the Remnic memory directory — it is read-only from your perspective.
+- **Respect missing files.** If a file does not exist, move on silently.
+  Never create placeholder Remnic files.
+
+## Failure handling
+
+- Remnic base directory missing: no-op. Remnic has nothing for this session.
+- Namespace directory missing: try the `shared` namespace, then give up.
+- Malformed file: skip it and continue.
+- Never block consolidation on a Remnic read error.
+
+## Quick recipe
+
+For a typical consolidation run:
+
+1. Resolve `<remnic-home>` from `$REMNIC_HOME` or `~/.remnic`.
+2. Resolve `<namespace>` from the session cwd using the rule above.
+3. Read `<remnic-home>/memories/<namespace>/MEMORY.md` if present.
+4. Read `<remnic-home>/memories/shared/MEMORY.md` if present.
+5. If the session produced or used a named workflow, read
+   `<remnic-home>/memories/<namespace>/skills/<name>/SKILL.md`.
+6. If you need more context, peek at the newest file under
+   `<remnic-home>/memories/<namespace>/rollout_summaries/`.
+7. Fold confirmed facts and preferences into the consolidated output and
+   cite them with `<oai-mem-citation />`.
+
+That is the whole extension. Keep it tight, cite your sources, and never
+invent Remnic content you did not read.

package/dist/connectors/codex/resources/namespace-cheatsheet.md

@@ -0,0 +1,48 @@
+# Remnic Namespace Cheatsheet
+
+Remnic partitions memories into **namespaces** so multiple projects and
+contexts can share a single Remnic home without bleeding into each other.
+When the Codex consolidation sub-agent reads Remnic files, it has to pick
+the right namespace directory for the session it is summarizing. This
+cheatsheet documents the resolution rule.
+
+## Resolution rule (in order)
+
+1. **Explicit override in the session.** If the user or the transcript
+   explicitly names a Remnic namespace, use that value verbatim.
+2. **Project anchor walk.** Starting from the session's working directory,
+   walk upward until you find any of:
+   - `.git/`
+   - `.remnic/namespace` file (highest priority if present)
+   - `package.json`
+   - `pyproject.toml`
+   - `Cargo.toml`
+   - `go.mod`
+   Use the basename of the anchor directory, lowercased, with whitespace
+   replaced by `-`.
+3. **Fallback.** If nothing above matches, use the namespace `default`.
+4. **Shared overlay.** In addition to the resolved namespace, always also
+   check the `shared` namespace for cross-project content.
+
+## Examples
+
+| Session cwd                              | Anchor               | Namespace       |
+|------------------------------------------|----------------------|-----------------|
+| `/home/user/code/my-app/src`             | `/home/user/code/my-app/.git`     | `my-app`        |
+| `/home/user/code/Data Pipeline`          | `.git`               | `data-pipeline` |
+| `/tmp/scratch`                           | (none)               | `default`       |
+| `/work/research/` (contains `.remnic/namespace` = `lab`) | `.remnic/namespace` | `lab`  |
+
+## Why it matters
+
+If the consolidation agent reads from the wrong namespace, it will either
+miss relevant project-specific memories (false negative) or drag unrelated
+content into the summary (false positive). Getting the namespace right keeps
+Remnic's signal-to-noise ratio high.
+
+## What the extension does with this
+
+The consolidation sub-agent reads `MEMORY.md`, `memory_summary.md`, any
+relevant `skills/<name>/SKILL.md`, and newest `rollout_summaries/*.md`
+under the resolved namespace, plus the `shared` namespace overlay. All
+reads are filesystem-only — no CLI, no network, no MCP.

package/dist/contradiction-review-WIUBAR52.js

@@ -0,0 +1,21 @@
+import {
+  computePairId,
+  isCoolingDown,
+  listPairs,
+  memoryHashesChanged,
+  readPair,
+  resolvePair,
+  writePair,
+  writePairs
+} from "./chunk-YNB73F22.js";
+export {
+  computePairId,
+  isCoolingDown,
+  listPairs,
+  memoryHashesChanged,
+  readPair,
+  resolvePair,
+  writePair,
+  writePairs
+};
+//# sourceMappingURL=contradiction-review-WIUBAR52.js.map

package/dist/contradiction-review-WIUBAR52.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}