@kisev/memomatic 1.0.0-dev.46.gfbe1e4c6992e → 1.0.0-dev.47.gcb218d104bc4

package/README.md

@@ -19,18 +19,42 @@ The `@kisev/agentomatic` installer deploys the OpenCode plugin automatically;
 standalone use runs the CLI:
 
 ```bash
-memomatic dream --dry-run
+memomatic process    # validate the inbox and index accepted entries (no model)
+memomatic dream      # full sweep: inbox + sessions + consolidation
 ```
 
 The nightly sweep is scheduled by the systemd user units in `assets/systemd/`
 (`memomatic-dream.service` and `memomatic-dream.timer`).
 
+## Inbox
+
+All writes are asynchronous. Skills, agents, and the `memory_write` tool
+append Markdown entry lines to `$XDG_STATE_HOME/memomatic/inbox/`:
+
+```markdown
+- Durable outcome in one sentence. <!-- source: team-retro --> <!-- key: stable-id -->
+```
+
+The next `process` or `dream` pass validates drops, applies `never-save`
+rules, deduplicates exact texts, supersedes entries sharing a `key`, rebuilds
+the SQLite index with batch embeddings, and moves rejected drops to
+`inbox/rejected/`. Producers detect the inbox by presence and skip silently
+when memomatic is absent.
+
+Every entry can carry a `source` annotation. Visibility derives from it:
+`team-*`, `gitlab`, and `spec-manage` entries may be quoted in team-facing
+artifacts; every other source (`people-journal`, `stopit`,
+`mattermost-triage`, `task-*`, `docs-*`, `user`) is personal-only. The label
+is exposed in search responses and session bootstrap blocks.
+
 ## Surfaces
 
-- `memomatic` CLI: corpus inspection and the `dream` sweep.
+- `memomatic` CLI: `process`, `dream`, `search`, `status`, `index`.
 - MCP stdio server with `memory_search`, `memory_get`, `memory_write`, and
   `memory_forget` tools.
-- The OpenCode plugin re-exported by `@kisev/agentomatic`.
+- The OpenCode plugin re-exported by `@kisev/agentomatic`; its bootstrap
+  injects curated memory plus project- and trigger-matched recall blocks
+  resolved from the session database (`projects` map in `settings.json`).
 
 Nothing is deleted without the explicit directives documented in
 `MEMORY_RULES.md`.

package/README.ru.md

@@ -19,17 +19,41 @@ npm install @kisev/memomatic
 автономное использование — через CLI:
 
 ```bash
-memomatic dream --dry-run
+memomatic process    # валидация inbox и индексация принятого (без модели)
+memomatic dream      # полный проход: inbox + сессии + консолидация
 ```
 
 Ночной проход планируют user-юниты systemd из `assets/systemd/`
 (`memomatic-dream.service` и `memomatic-dream.timer`).
 
+## Inbox
+
+Все записи асинхронны. Скиллы, агенты и инструмент `memory_write` кладут
+строки записей Markdown в `$XDG_STATE_HOME/memomatic/inbox/`:
+
+```markdown
+- Durable-вывод одним предложением. <!-- source: team-retro --> <!-- key: stable-id -->
+```
+
+Следующий проход `process` или `dream` валидирует дропы, применяет правила
+`never-save`, дедуплицирует точные тексты, замещает записи с тем же `key`,
+пересобирает SQLite-индекс с батч-эмбеддингами и переносит отклонённое в
+`inbox/rejected/`. Продюсеры детектируют inbox по наличию и молча
+пропускают дроп, если memomatic нет.
+
+Каждая запись может нести аннотацию `source`. Из неё выводится видимость:
+записи `team-*`, `gitlab` и `spec-manage` можно цитировать в командных
+артефактах; остальные источники (`people-journal`, `stopit`,
+`mattermost-triage`, `task-*`, `docs-*`, `user`) — personal-only. Метка
+возвращается в поиске и в bootstrap-блоках сессий.
+
 ## Поверхности
 
-- CLI `memomatic`: инспекция корпуса и проход `dream`.
+- CLI `memomatic`: `process`, `dream`, `search`, `status`, `index`.
 - MCP-сервер stdio с инструментами `memory_search`, `memory_get`,
   `memory_write` и `memory_forget`.
-- Плагин OpenCode, реэкспортируемый пакетом `@kisev/agentomatic`.
+- Плагин OpenCode, реэкспортируемый пакетом `@kisev/agentomatic`; его
+  bootstrap добавляет к кураторской памяти блоки напоминаний по проекту и
+  trigger-фразам (контекст сессии и маппинг `projects` из `settings.json`).
 
 Без явных директив, описанных в `MEMORY_RULES.md`, ничего не удаляется.

package/dist/bootstrap.d.ts

@@ -0,0 +1,19 @@
+import type { MemomaticContext } from "./service.js";
+export type SessionFacts = {
+    directory: string | null;
+    title: string | null;
+    firstMessage: string | null;
+};
+export type BootstrapOptions = {
+    curatedBudgetChars?: number;
+    episodicBudgetChars?: number;
+};
+/** Longest-prefix match of a working directory against the projects map. */
+export declare function resolveProject(directory: string | null, projects: Record<string, string>): string | null;
+/**
+ * Build the session bootstrap context: curated MEMORY.md and USER.md heads,
+ * plus episodic entries matched by project annotation and trigger phrases.
+ * Every episodic line carries its source visibility so team-facing artifacts
+ * never quote personal-only memory.
+ */
+export declare function bootstrapContext(context: MemomaticContext, facts: SessionFacts, options?: BootstrapOptions): Promise<string | null>;

package/dist/bootstrap.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { visibilityForSource } from "./visibility.js";
+const DEFAULT_CURATED_BUDGET = 4_000;
+const DEFAULT_EPISODIC_BUDGET = 1_500;
+const MAX_BLOCK_ENTRIES = 8;
+/** Longest-prefix match of a working directory against the projects map. */
+export function resolveProject(directory, projects) {
+    if (!directory)
+        return null;
+    let best = null;
+    for (const [prefix, name] of Object.entries(projects)) {
+        if (directory === prefix || directory.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`))
+            if (!best || prefix.length > best.prefix.length)
+                best = { prefix, name };
+    }
+    return best?.name ?? null;
+}
+function renderEntry(entry) {
+    const visibility = visibilityForSource(entry.source);
+    const label = entry.source ? `source: ${entry.source}, ${visibility}-only` : `${visibility}-only`;
+    const text = entry.text.startsWith("- ") ? entry.text.slice(2) : entry.text;
+    return `- ${text} (${label})`;
+}
+function rankEntries(entries) {
+    return [...entries].sort((left, right) => {
+        if (right.importance !== left.importance)
+            return right.importance - left.importance;
+        return (right.observedAt ?? 0) - (left.observedAt ?? 0);
+    });
+}
+function fitsBudget(lines, budget) {
+    const result = [];
+    let used = 0;
+    for (const line of lines) {
+        if (result.length >= MAX_BLOCK_ENTRIES)
+            break;
+        if (used + line.length > budget)
+            break;
+        result.push(line);
+        used += line.length + 1;
+    }
+    return result;
+}
+/**
+ * Build the session bootstrap context: curated MEMORY.md and USER.md heads,
+ * plus episodic entries matched by project annotation and trigger phrases.
+ * Every episodic line carries its source visibility so team-facing artifacts
+ * never quote personal-only memory.
+ */
+export async function bootstrapContext(context, facts, options = {}) {
+    const curatedBudget = options.curatedBudgetChars ?? DEFAULT_CURATED_BUDGET;
+    const episodicBudget = options.episodicBudgetChars ?? DEFAULT_EPISODIC_BUDGET;
+    const blocks = [];
+    for (const file of [context.paths.memoryFile, context.paths.userFile]) {
+        const content = await readFile(file, "utf8").catch(() => undefined);
+        if (content === undefined || !content.trim())
+            continue;
+        const name = file.slice(file.lastIndexOf("/") + 1);
+        blocks.push(`# Memomatic ${name}\n\n${content.trim().slice(0, curatedBudget)}`);
+    }
+    const entries = context.store.allEntries().filter((entry) => entry.status === null);
+    const project = resolveProject(facts.directory, context.settings.projects);
+    const usedTexts = new Set();
+    if (project) {
+        const lines = rankEntries(entries.filter((entry) => entry.kind === "episodic" && entry.project === project)).map((entry) => {
+            usedTexts.add(entry.text);
+            return renderEntry(entry);
+        });
+        const fitted = fitsBudget(lines, episodicBudget);
+        if (fitted.length)
+            blocks.push(`# Memomatic project recall (${project})\n\n${fitted.join("\n")}\n\nEntries marked personal-only must never be quoted in team-facing artifacts.`);
+    }
+    const haystack = [facts.title ?? "", facts.firstMessage ?? ""].join("\n").toLowerCase();
+    if (haystack.trim()) {
+        const triggered = rankEntries(entries.filter((entry) => !usedTexts.has(entry.text) &&
+            entry.trigger.some((phrase) => phrase.trim() && haystack.includes(phrase.toLowerCase())))).map((entry) => renderEntry(entry));
+        const fitted = fitsBudget(triggered, episodicBudget);
+        if (fitted.length)
+            blocks.push(`# Memomatic triggered recall\n\n${fitted.join("\n")}\n\nEntries marked personal-only must never be quoted in team-facing artifacts.`);
+    }
+    if (!blocks.length)
+        return null;
+    return `${blocks.join("\n\n")}\n\nUse memory_search for details and memory_write to queue durable outcomes. Never re-save content that is already present in this memory.`;
+}

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { openMemomatic, rebuildIndex, searchMemory } from "./service.js";
 import { runDream } from "./dream.js";
+import { processInbox, withRunLock } from "./inbox.js";
 import { OpenCodeExecutor } from "./executor.js";
 import { handleMcpRequest } from "./mcp.js";
 const USAGE = `usage: memomatic <command> [args]
 
 commands:
+  process [--dry-run]      validate the inbox and move accepted entries into the corpus
   dream [--dry-run]        run the consolidation sweep (scheduled by memomatic-dream.timer)
   search <query>           search memory from the command line
   status                   report corpus and index status
@@ -35,16 +37,20 @@ async function main() {
     }
     const context = await openMemomatic();
     try {
-        if (command === "dream") {
+        if (command === "dream" || command === "process") {
             const dryRun = rest.includes("--dry-run");
-            const executor = context.settings.dream.model
-                ? new OpenCodeExecutor({
-                    model: context.settings.dream.model,
-                    variant: context.settings.dream.variant,
-                })
-                : null;
-            const report = await runDream(context, executor, { dryRun });
-            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            const result = await withRunLock(context.paths, async () => {
+                if (command === "process")
+                    return processInbox(context, { dryRun });
+                const executor = context.settings.dream.model
+                    ? new OpenCodeExecutor({
+                        model: context.settings.dream.model,
+                        variant: context.settings.dream.variant,
+                    })
+                    : null;
+                return runDream(context, executor, { dryRun });
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             return;
         }
         if (command === "search") {

package/dist/dream.d.ts

@@ -1,6 +1,8 @@
+import { type InboxReport } from "./inbox.js";
 import { type ModelExecutor } from "./executor.js";
 import type { MemomaticContext } from "./service.js";
 export type DreamReport = {
+    inbox: InboxReport;
     sessionsIngested: number;
     candidatesExtracted: number;
     promoted: string[];

package/dist/dream.js

@@ -1,5 +1,6 @@
 import { entryLine, parseEntryLine } from "./entries.js";
 import { appendDailyEntry, appendDreams, readTextIfExists, writeCorpusFile } from "./corpus.js";
+import { processInbox } from "./inbox.js";
 import { promotionCandidates } from "./gates.js";
 import { extractJson } from "./executor.js";
 import { loadRecentSessions, opencodeDatabasePath } from "./ingest.js";
@@ -109,6 +110,16 @@ async function ingestSessions(context, executor) {
 export async function runDream(context, executor, options = {}) {
     const dryRun = options.dryRun === true;
     const report = {
+        inbox: {
+            filesProcessed: 0,
+            filesRejected: 0,
+            entriesAppended: 0,
+            entriesSuperseded: 0,
+            entriesDuplicated: 0,
+            linesForbidden: 0,
+            linesInvalid: 0,
+            dryRun,
+        },
         sessionsIngested: 0,
         candidatesExtracted: 0,
         promoted: [],
@@ -120,6 +131,7 @@ export async function runDream(context, executor, options = {}) {
         dryRun,
     };
     await reindex(context.paths, context.settings, context.store);
+    report.inbox = await processInbox(context, { dryRun });
     const ingestion = await ingestSessions(context, executor);
     report.sessionsIngested = ingestion.sessions;
     report.candidatesExtracted = ingestion.extracted.length;
@@ -167,6 +179,10 @@ export async function runDream(context, executor, options = {}) {
         report.archived = await archiveOldEpisodic(context);
     await reindex(context.paths, context.settings, context.store);
     const summary = [
+        `- inbox files processed: ${report.inbox.filesProcessed}`,
+        `- inbox entries appended: ${report.inbox.entriesAppended}`,
+        `- inbox entries superseded: ${report.inbox.entriesSuperseded}`,
+        `- inbox files rejected: ${report.inbox.filesRejected}`,
         `- sessions ingested: ${report.sessionsIngested}`,
         `- candidates extracted: ${report.candidatesExtracted}`,
         `- promoted: ${report.promoted.length}${report.promoted.length ? ` (${report.promoted.join(", ")})` : ""}`,

package/dist/entries.d.ts

@@ -7,6 +7,8 @@ export type EntryAnnotations = {
     importance?: number;
     trigger?: string[];
     pinned?: boolean;
+    source?: string;
+    target?: "episodic" | "curated" | "user";
 };
 export type CorpusEntry = {
     file: string;
@@ -18,8 +20,12 @@ export declare function parseEntryLine(line: string): {
     text: string;
     annotations: EntryAnnotations;
 } | null;
-export declare function serializeAnnotations(annotations: EntryAnnotations): string;
-export declare function entryLine(text: string, annotations: EntryAnnotations): string;
+export declare function serializeAnnotations(annotations: EntryAnnotations, options?: {
+    dropTarget?: boolean;
+}): string;
+export declare function entryLine(text: string, annotations: EntryAnnotations, options?: {
+    dropTarget?: boolean;
+}): string;
 export declare function entryKey(entry: CorpusEntry): string | null;
 export declare function entryImportance(entry: CorpusEntry): number;
 export declare function entryObservedAt(entry: CorpusEntry): number;

package/dist/entries.js

@@ -1,3 +1,4 @@
+const SOURCE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const TRAILING_ANNOTATION = /\s*<!--\s*([a-z-]+):\s*([^<]*?)\s*-->\s*$/;
 export function parseEntryLine(line) {
     let value = line.trimEnd();
@@ -11,14 +12,26 @@ export function parseEntryLine(line) {
         const name = match[1];
         const raw = match[2];
         let consumed = true;
-        if (name === "key" || name === "project" || name === "observed") {
+        if (name === "key" || name === "project" || name === "observed" || name === "source") {
             if (name === "observed")
                 annotations.observed = raw;
             else if (name === "project")
                 annotations.project = raw;
+            else if (name === "source") {
+                if (SOURCE_PATTERN.test(raw))
+                    annotations.source = raw;
+                else
+                    consumed = false;
+            }
             else
                 annotations.key = raw;
         }
+        else if (name === "target") {
+            if (raw === "episodic" || raw === "curated" || raw === "user")
+                annotations.target = raw;
+            else
+                consumed = false;
+        }
         else if (name === "status") {
             if (raw === "active" || raw === "superseded")
                 annotations.status = raw;
@@ -60,7 +73,7 @@ export function parseEntryLine(line) {
     }
     return { text: value, annotations };
 }
-export function serializeAnnotations(annotations) {
+export function serializeAnnotations(annotations, options = {}) {
     const parts = [];
     if (annotations.key)
         parts.push(`key: ${annotations.key}`);
@@ -78,10 +91,14 @@ export function serializeAnnotations(annotations) {
         parts.push(`trigger: ${annotations.trigger.join("; ")}`);
     if (annotations.pinned)
         parts.push("pinned: true");
+    if (annotations.source)
+        parts.push(`source: ${annotations.source}`);
+    if (!options.dropTarget && annotations.target)
+        parts.push(`target: ${annotations.target}`);
     return parts.map((part) => `<!-- ${part} -->`).join(" ");
 }
-export function entryLine(text, annotations) {
-    const suffix = serializeAnnotations(annotations);
+export function entryLine(text, annotations, options = {}) {
+    const suffix = serializeAnnotations(annotations, options);
     return `- ${text}${suffix ? ` ${suffix}` : ""}`;
 }
 export function entryKey(entry) {

package/dist/inbox.d.ts

@@ -0,0 +1,32 @@
+import type { MemomaticContext } from "./service.js";
+import type { MemomaticPaths } from "./paths.js";
+export type InboxReport = {
+    filesProcessed: number;
+    filesRejected: number;
+    entriesAppended: number;
+    entriesSuperseded: number;
+    entriesDuplicated: number;
+    linesForbidden: number;
+    linesInvalid: number;
+    dryRun: boolean;
+};
+export declare function inboxFileName(source: string, now?: Date): string;
+/**
+ * Append one inbox drop file. Producers write Markdown entry lines that the
+ * deterministic `process` pass later validates, gates, and moves into the
+ * corpus. Nothing here touches corpus files.
+ */
+export declare function dropToInbox(paths: MemomaticPaths, lines: string[], source: string): Promise<string>;
+/**
+ * Deterministic inbox pass: validate entry lines, enforce never-save rules,
+ * deduplicate exact texts, supersede entries sharing a key, route user-origin
+ * targets, then rebuild the index with embeddings. No model turns.
+ */
+export declare function processInbox(context: MemomaticContext, options?: {
+    dryRun?: boolean;
+}): Promise<InboxReport>;
+/**
+ * Serialize whole runs (dream or process) with a stale-tolerant lock file so a
+ * nightly sweep and a manual CLI invocation never mutate the corpus together.
+ */
+export declare function withRunLock<T>(paths: MemomaticPaths, work: () => Promise<T>): Promise<T>;

package/dist/inbox.js

@@ -0,0 +1,203 @@
+import { mkdir, open, readdir, rename, rm, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { writeAtomic } from "@kisev/safe-fs";
+import { appendDailyEntry, readTextIfExists, replaceEntryLine, writeCorpusFile } from "./corpus.js";
+import { entryLine, parseEntryLine } from "./entries.js";
+import { corpusFiles, reindex } from "./search.js";
+import { isForbidden } from "./rules.js";
+const SOURCE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const LIST_PREFIX = /^- /;
+/** parseEntryLine keeps the leading "- "; strip it before re-serializing. */
+function entryText(parsed) {
+    return LIST_PREFIX.test(parsed.text) ? parsed.text.slice(2) : parsed.text;
+}
+const LOCK_STALE_MS = 30 * 60_000;
+export function inboxFileName(source, now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").slice(0, 15);
+    return `${source}-${stamp}-${randomBytes(4).toString("hex")}.md`;
+}
+/**
+ * Append one inbox drop file. Producers write Markdown entry lines that the
+ * deterministic `process` pass later validates, gates, and moves into the
+ * corpus. Nothing here touches corpus files.
+ */
+export async function dropToInbox(paths, lines, source) {
+    if (!SOURCE_PATTERN.test(source))
+        throw new Error(`inbox source is invalid: ${source}`);
+    const content = `${lines.filter((line) => line.trim()).join("\n")}\n`;
+    if (!content.trim())
+        throw new Error("inbox drop is empty");
+    const file = join(paths.inboxDir, inboxFileName(source));
+    await writeAtomic(file, Buffer.from(content, "utf8"), 0o600);
+    return file;
+}
+async function scanCorpus(paths) {
+    const index = { texts: new Set(), keys: new Map() };
+    for (const file of await corpusFiles(paths)) {
+        const markdown = (await readTextIfExists(file)) ?? "";
+        const lines = markdown.split("\n");
+        for (let position = 0; position < lines.length; position += 1) {
+            const parsed = parseEntryLine(lines[position]);
+            if (!parsed)
+                continue;
+            index.texts.add(parsed.text);
+            if (parsed.annotations.key && parsed.annotations.status !== "superseded")
+                index.keys.set(parsed.annotations.key, { file, line: position + 1 });
+        }
+    }
+    return index;
+}
+async function moveRejected(paths, name) {
+    await mkdir(paths.rejectedDir, { mode: 0o700, recursive: true });
+    await rename(join(paths.inboxDir, name), join(paths.rejectedDir, name));
+}
+async function appendLine(context, file, line) {
+    const current = (await readTextIfExists(file)) ?? "";
+    await writeCorpusFile(context.paths, file, `${current.trimEnd()}\n${line}\n`);
+}
+function routeFor(annotations) {
+    if (annotations.target === "user" && annotations.origin === "user")
+        return "user";
+    if (annotations.target === "curated" && annotations.origin === "user")
+        return "curated";
+    return "episodic";
+}
+/**
+ * Deterministic inbox pass: validate entry lines, enforce never-save rules,
+ * deduplicate exact texts, supersede entries sharing a key, route user-origin
+ * targets, then rebuild the index with embeddings. No model turns.
+ */
+export async function processInbox(context, options = {}) {
+    const dryRun = options.dryRun === true;
+    const report = {
+        filesProcessed: 0,
+        filesRejected: 0,
+        entriesAppended: 0,
+        entriesSuperseded: 0,
+        entriesDuplicated: 0,
+        linesForbidden: 0,
+        linesInvalid: 0,
+        dryRun,
+    };
+    const names = (await readdir(context.paths.inboxDir).catch(() => []))
+        .filter((name) => name.endsWith(".md"))
+        .sort();
+    if (!names.length)
+        return report;
+    const corpus = await scanCorpus(context.paths);
+    for (const name of names) {
+        const markdown = (await readTextIfExists(join(context.paths.inboxDir, name))) ?? "";
+        const rawLines = markdown.split("\n");
+        const parsedLines = rawLines.filter((line) => line.trim()).map((line) => parseEntryLine(line));
+        report.linesInvalid += parsedLines.filter((parsed) => !parsed).length;
+        const allowed = parsedLines.filter((parsed) => {
+            if (!parsed)
+                return false;
+            if (isForbidden(parsed.text, context.rules)) {
+                report.linesForbidden += 1;
+                return false;
+            }
+            return true;
+        });
+        if (!allowed.length) {
+            if (!dryRun)
+                await moveRejected(context.paths, name);
+            report.filesRejected += 1;
+            continue;
+        }
+        let accepted = false;
+        for (const parsed of allowed) {
+            if (corpus.texts.has(parsed.text)) {
+                report.entriesDuplicated += 1;
+                continue;
+            }
+            const annotations = {
+                ...parsed.annotations,
+                target: undefined,
+                observed: parsed.annotations.observed ?? new Date().toISOString().slice(0, 10),
+            };
+            const line = entryLine(entryText(parsed), annotations, { dropTarget: true });
+            const route = routeFor(parsed.annotations);
+            const existing = route === "episodic" && parsed.annotations.key
+                ? corpus.keys.get(parsed.annotations.key)
+                : undefined;
+            if (existing) {
+                if (!dryRun)
+                    await replaceEntryLine(context.paths, existing.file, existing.line, line);
+                report.entriesSuperseded += 1;
+            }
+            else if (route === "user" || route === "curated") {
+                if (!dryRun)
+                    await appendLine(context, route === "user" ? context.paths.userFile : context.paths.memoryFile, line);
+                report.entriesAppended += 1;
+            }
+            else {
+                if (!dryRun)
+                    await appendDailyEntry(context.paths, line);
+                report.entriesAppended += 1;
+            }
+            corpus.texts.add(parsed.text);
+            accepted = true;
+        }
+        if (accepted) {
+            if (!dryRun)
+                await unlink(join(context.paths.inboxDir, name)).catch(() => undefined);
+            report.filesProcessed += 1;
+        }
+        else {
+            if (!dryRun)
+                await moveRejected(context.paths, name);
+            report.filesRejected += 1;
+        }
+    }
+    if (!dryRun)
+        await reindex(context.paths, context.settings, context.store);
+    return report;
+}
+/**
+ * Serialize whole runs (dream or process) with a stale-tolerant lock file so a
+ * nightly sweep and a manual CLI invocation never mutate the corpus together.
+ */
+export async function withRunLock(paths, work) {
+    const acquire = async () => {
+        try {
+            const handle = await open(paths.runLockFile, "wx", 0o600);
+            try {
+                await handle.writeFile(`${process.pid} ${new Date().toISOString()}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            try {
+                const handle = await open(paths.runLockFile, "r");
+                try {
+                    const info = await handle.stat();
+                    stale = Date.now() - info.mtimeMs > LOCK_STALE_MS;
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch {
+                return;
+            }
+            if (!stale)
+                throw new Error("another memomatic run is active");
+            await rm(paths.runLockFile, { force: true });
+            return acquire();
+        }
+    };
+    await acquire();
+    try {
+        return await work();
+    }
+    finally {
+        await rm(paths.runLockFile, { force: true }).catch(() => undefined);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { writeCorpusFile } from "./corpus.js";
 export { entryLine, parseEntryLine } from "./entries.js";
+export { visibilityForSource } from "./visibility.js";
+export { dropToInbox, processInbox, withRunLock } from "./inbox.js";
 export { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
 export type { MemomaticContext } from "./service.js";
+export { bootstrapContext, resolveProject } from "./bootstrap.js";
+export { opencodeDatabasePath, sessionFacts } from "./ingest.js";

package/dist/index.js

@@ -1,3 +1,7 @@
 export { writeCorpusFile } from "./corpus.js";
 export { entryLine, parseEntryLine } from "./entries.js";
+export { visibilityForSource } from "./visibility.js";
+export { dropToInbox, processInbox, withRunLock } from "./inbox.js";
 export { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
+export { bootstrapContext, resolveProject } from "./bootstrap.js";
+export { opencodeDatabasePath, sessionFacts } from "./ingest.js";

package/dist/ingest.d.ts

@@ -9,6 +9,17 @@ export type IngestSession = {
     }>;
 };
 export declare function opencodeDatabasePath(): string;
+export type SessionFacts = {
+    directory: string | null;
+    title: string | null;
+    firstMessage: string | null;
+};
+/**
+ * Resolve session context for the bootstrap block: working directory, title,
+ * and the first user message, read-only from the OpenCode database. Returns
+ * nulls when the session or database is unavailable.
+ */
+export declare function sessionFacts(databaseFile: string, sessionId: string): SessionFacts;
 export declare function loadRecentSessions(databaseFile: string, afterTimeCreated: number, options?: {
     maxSessions: number;
     maxCharsPerSession: number;

package/dist/ingest.js

@@ -9,6 +9,61 @@ export function opencodeDatabasePath() {
         throw new Error("XDG_DATA_HOME must be an absolute path");
     return join(base, "opencode", "opencode.db");
 }
+/**
+ * Resolve session context for the bootstrap block: working directory, title,
+ * and the first user message, read-only from the OpenCode database. Returns
+ * nulls when the session or database is unavailable.
+ */
+export function sessionFacts(databaseFile, sessionId) {
+    let db;
+    try {
+        db = new DatabaseSync(databaseFile, { readOnly: true });
+    }
+    catch {
+        return { directory: null, title: null, firstMessage: null };
+    }
+    try {
+        const session = db
+            .prepare("SELECT directory, title FROM session WHERE id = ?;")
+            .get(sessionId);
+        let firstMessage = null;
+        const rows = db
+            .prepare(`SELECT data FROM message WHERE session_id = ? ORDER BY time_created ASC LIMIT 20;`)
+            .all(sessionId);
+        for (const row of rows) {
+            try {
+                const parsed = JSON.parse(row.data);
+                if (parsed.role !== "user")
+                    continue;
+                const texts = [];
+                for (const part of parsed.parts ?? []) {
+                    const value = part;
+                    if (value.type === "text" && typeof value.text === "string")
+                        texts.push(value.text);
+                }
+                const text = texts.join("\n").trim();
+                if (text) {
+                    firstMessage = text;
+                    break;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return {
+            directory: session?.directory ?? null,
+            title: session?.title ?? null,
+            firstMessage,
+        };
+    }
+    catch {
+        return { directory: null, title: null, firstMessage: null };
+    }
+    finally {
+        db.close();
+    }
+}
 export function loadRecentSessions(databaseFile, afterTimeCreated, options = {
     maxSessions: 20,
     maxCharsPerSession: 24_000,

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
+import { visibilityForSource } from "./visibility.js";
 const PROTOCOL_VERSION = "2025-06-18";
 const TOOLS = [
     {
@@ -25,7 +26,7 @@ const TOOLS = [
         name: "memory_get",
     },
     {
-        description: "Save a memory entry. Use for standing decisions with rationale, discoveries, failed attempts with rejection reasons, session outcomes, and action-sensitive boundaries. Respect MEMORY_RULES.md; never-save topics are rejected.",
+        description: "Queue a memory entry for the next process/dream pass. Use for standing decisions with rationale, discoveries, failed attempts with rejection reasons, session outcomes, and action-sensitive boundaries. Respect MEMORY_RULES.md; never-save topics are rejected immediately.",
         inputSchema: {
             additionalProperties: false,
             properties: {
@@ -34,6 +35,10 @@ const TOOLS = [
                 origin: { enum: ["user", "agent"], type: "string" },
                 pinned: { type: "boolean" },
                 project: { type: "string" },
+                source: {
+                    description: "Originating skill or producer in kebab-case, e.g. team-retro",
+                    type: "string",
+                },
                 target: { enum: ["episodic", "curated", "user"], type: "string" },
                 text: { type: "string" },
                 trigger: { items: { type: "string" }, type: "array" },
@@ -71,6 +76,8 @@ async function callTool(name, args) {
                     line: hit.entry.line,
                     score: Number(hit.score.toFixed(4)),
                     snippet: hit.snippet,
+                    source: hit.entry.source,
+                    visibility: visibilityForSource(hit.entry.source),
                 }));
             }
             case "memory_get": {
@@ -87,19 +94,29 @@ async function callTool(name, args) {
             case "memory_write": {
                 if (typeof args.text !== "string" || !args.text.trim())
                     throw new Error("text is required");
+                const source = typeof args.source === "string" && args.source
+                    ? args.source
+                    : args.origin === "user"
+                        ? "user"
+                        : "agent";
                 const file = await writeEntry(context, {
                     importance: typeof args.importance === "number" ? args.importance : undefined,
                     key: typeof args.key === "string" ? args.key : undefined,
                     origin: args.origin === "user" ? "user" : "agent",
                     pinned: args.pinned === true,
                     project: typeof args.project === "string" ? args.project : undefined,
+                    source,
                     target: args.target === "curated" || args.target === "user" ? args.target : "episodic",
                     text: args.text,
                     trigger: Array.isArray(args.trigger)
                         ? args.trigger.filter((item) => typeof item === "string")
                         : undefined,
                 });
-                return { file: file.replace(`${context.paths.stateRoot}/`, ""), saved: true };
+                return {
+                    file: file.replace(`${context.paths.stateRoot}/`, ""),
+                    flushHint: "run `memomatic process` to index queued entries immediately",
+                    queued: true,
+                };
             }
             case "memory_forget": {
                 if (typeof args.file !== "string" || typeof args.line !== "number")

package/dist/paths.d.ts

@@ -10,6 +10,9 @@ export type MemomaticPaths = {
     archiveDir: string;
     historyDir: string;
     indexFile: string;
+    inboxDir: string;
+    rejectedDir: string;
+    runLockFile: string;
 };
 export declare function memomaticPaths(): MemomaticPaths;
 export declare function verifyMemomaticRoots(paths: MemomaticPaths): Promise<void>;

package/dist/paths.js

@@ -39,6 +39,9 @@ export function memomaticPaths() {
         archiveDir: join(stateRoot, "archive"),
         historyDir: join(stateRoot, "history"),
         indexFile: join(stateRoot, "index.sqlite"),
+        inboxDir: join(stateRoot, "inbox"),
+        rejectedDir: join(stateRoot, "inbox", "rejected"),
+        runLockFile: join(stateRoot, "run.lock"),
     };
 }
 export async function verifyMemomaticRoots(paths) {

package/dist/rules.d.ts

@@ -3,6 +3,7 @@ export type MemoryRules = {
     autoClean: {
         olderThanDays: number;
         scope: "episodic";
+        source?: string;
     } | null;
 };
 export declare const emptyRules: () => MemoryRules;

package/dist/rules.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 const NEVER_SAVE = /^-\s*never-save:\s*(.+?)\s*$/gim;
-const AUTO_CLEAN = /^-\s*auto-clean:\s*older-than=(\d+)d\s+scope=episodic\s*$/im;
+const AUTO_CLEAN = /^-\s*auto-clean:\s*older-than=(\d+)d\s+scope=episodic(?:\s+source=([a-z0-9-]+))?\s*$/im;
 export const emptyRules = () => ({ neverSave: [], autoClean: null });
 export function parseRules(markdown) {
     const rules = emptyRules();
@@ -13,7 +13,11 @@ export function parseRules(markdown) {
     if (autoClean) {
         const days = Number.parseInt(autoClean[1], 10);
         if (Number.isFinite(days) && days > 0)
-            rules.autoClean = { olderThanDays: days, scope: "episodic" };
+            rules.autoClean = {
+                olderThanDays: days,
+                scope: "episodic",
+                source: autoClean[2],
+            };
     }
     return rules;
 }

package/dist/search.d.ts

@@ -6,6 +6,7 @@ export type SearchHit = {
     score: number;
     snippet: string;
 };
+export declare function corpusFiles(paths: MemomaticPaths): Promise<string[]>;
 export declare function reindex(paths: MemomaticPaths, settings: MemomaticSettings, store: MemoryStore): Promise<number>;
 export declare function search(store: MemoryStore, query: string, settings: MemomaticSettings, options?: {
     includeArchived?: boolean;

package/dist/search.js

@@ -4,7 +4,7 @@ import { cosineSimilarity, stableIdFor } from "./store.js";
 import { entryKind, parseCorpusEntries } from "./corpus.js";
 import { entryImportance, entryObservedAt } from "./entries.js";
 import { embedTexts } from "./settings.js";
-async function corpusFiles(paths) {
+export async function corpusFiles(paths) {
     const files = [];
     for (const name of ["MEMORY.md", "USER.md"]) {
         const file = join(paths.stateRoot, name);
@@ -38,6 +38,7 @@ export async function reindex(paths, settings, store) {
                 origin: entry.annotations.origin ?? null,
                 observedAt: Number.isNaN(entryObservedAt(entry)) ? null : entryObservedAt(entry),
                 status: entry.annotations.status === "active" ? "active" : null,
+                source: entry.annotations.source ?? null,
             });
         }
     }

package/dist/service.d.ts

@@ -12,6 +12,7 @@ export type WriteRequest = {
     origin?: "user" | "agent";
     target?: "episodic" | "curated" | "user";
     pinned?: boolean;
+    source?: string;
 };
 export type MemomaticContext = {
     paths: MemomaticPaths;

package/dist/service.js

@@ -1,10 +1,21 @@
 import { entryLine } from "./entries.js";
-import { appendDailyEntry, archiveFile, readTextIfExists, replaceEntryLine } from "./corpus.js";
+import { archiveFile, readTextIfExists, replaceEntryLine } from "./corpus.js";
+import { dropToInbox } from "./inbox.js";
 import { isForbidden, loadRules } from "./rules.js";
 import { memomaticPaths } from "./paths.js";
 import { loadSettings } from "./settings.js";
 import { reindex, search } from "./search.js";
 import { MemoryStore } from "./store.js";
+import { stat } from "node:fs/promises";
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function openMemomatic() {
     const paths = memomaticPaths();
     const [settings, rules, store] = await Promise.all([
@@ -21,28 +32,19 @@ export async function writeEntry(context, request) {
     if (isForbidden(text, context.rules))
         throw new Error("memory text matches a never-save rule in MEMORY_RULES.md");
     const origin = request.origin ?? "agent";
-    const observed = new Date().toISOString().slice(0, 10);
     const line = entryLine(text, {
         key: request.key,
         status: origin === "user" && request.target === "user" ? "active" : undefined,
         origin,
-        observed,
+        observed: new Date().toISOString().slice(0, 10),
         project: request.project,
         importance: request.importance,
         trigger: request.trigger,
         pinned: request.pinned,
+        source: request.source ?? origin,
+        target: request.target,
     });
-    if (request.target === "curated" || request.target === "user") {
-        if (origin !== "user")
-            throw new Error("curated and user entries require origin=user");
-        const file = request.target === "user" ? context.paths.userFile : context.paths.memoryFile;
-        const current = (await readTextIfExists(file)) ?? "";
-        const next = `${current.trimEnd()}\n${line}\n`;
-        const { writeCorpusFile } = await import("./corpus.js");
-        await writeCorpusFile(context.paths, file, next);
-        return file;
-    }
-    return appendDailyEntry(context.paths, line);
+    return dropToInbox(context.paths, [line], request.source ?? origin);
 }
 export async function searchMemory(context, query) {
     return search(context.store, query, context.settings);
@@ -86,12 +88,17 @@ export async function archiveOldEpisodic(context) {
     const archived = [];
     if (!context.rules.autoClean)
         return archived;
-    const cutoff = Date.now() - context.rules.autoClean.olderThanDays * 86_400_000;
+    const rule = context.rules.autoClean;
+    const cutoff = Date.now() - rule.olderThanDays * 86_400_000;
     for (const entry of context.store.allEntries()) {
         if (entry.kind !== "episodic" || !entry.observedAt || entry.observedAt >= cutoff)
             continue;
+        if (rule.source && entry.source !== rule.source)
+            continue;
         if (entry.pinned)
             continue;
+        if (!(await exists(entry.file)))
+            continue;
         const alreadyDone = archived.includes(entry.file);
         if (!alreadyDone) {
             await archiveFile(context.paths, entry.file);

package/dist/settings.d.ts

@@ -3,6 +3,7 @@ export type MemomaticSettings = {
         url: string;
         model: string;
     } | null;
+    projects: Record<string, string>;
     dream: {
         model: string | null;
         variant: string | null;

package/dist/settings.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 export const defaultSettings = () => ({
     embedding: null,
+    projects: {},
     dream: {
         model: null,
         variant: null,
@@ -28,10 +29,19 @@ export function normalizeSettings(raw) {
     const defaults = defaultSettings();
     const source = (raw ?? {});
     const embedding = source.embedding;
+    const rawProjects = source.projects;
+    const projects = {};
+    if (rawProjects && typeof rawProjects === "object") {
+        for (const [prefix, name] of Object.entries(rawProjects)) {
+            if (typeof name === "string" && name.trim() && prefix.trim())
+                projects[prefix] = name.trim();
+        }
+    }
     return {
         embedding: embedding && typeof embedding.url === "string" && typeof embedding.model === "string"
             ? { url: embedding.url, model: embedding.model }
             : null,
+        projects,
         dream: mergeSection(defaults.dream, source.dream),
         search: mergeSection(defaults.search, source.search),
         archive: mergeSection(defaults.archive, source.archive),

package/dist/store.d.ts

@@ -14,6 +14,7 @@ export type IndexedEntry = {
     origin: "user" | "agent" | null;
     observedAt: number | null;
     status: "active" | null;
+    source: string | null;
 };
 export type VectorRow = {
     stableId: string;
@@ -25,6 +26,7 @@ export declare class MemoryStore {
     readonly db: DatabaseSync;
     private readonly fts;
     private constructor();
+    private migrate;
     static open(indexFile: string): Promise<MemoryStore>;
     private ensureFts;
     hasFts(): boolean;

package/dist/store.js

@@ -48,8 +48,14 @@ export class MemoryStore {
         this.db = new DatabaseSync(indexFile);
         this.db.exec("PRAGMA journal_mode = WAL;");
         this.db.exec(SCHEMA);
+        this.migrate();
         this.fts = this.ensureFts();
     }
+    migrate() {
+        const columns = this.db.prepare("PRAGMA table_info(entries);").all();
+        if (!columns.some((column) => column.name === "source"))
+            this.db.exec("ALTER TABLE entries ADD COLUMN source TEXT;");
+    }
     static async open(indexFile) {
         await mkdir(dirname(indexFile), { mode: 0o700, recursive: true });
         return new MemoryStore(indexFile);
@@ -78,9 +84,9 @@ export class MemoryStore {
                     continue;
                 seen.add(entry.stableId);
                 this.db
-                    .prepare(`INSERT INTO entries (stable_id, file, line, kind, key, text, trigger_phrases, importance, pinned, project, origin, observed_at, status)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(entry.stableId, entry.file, entry.line, entry.kind, entry.key, entry.text, JSON.stringify(entry.trigger), entry.importance, entry.pinned ? 1 : 0, entry.project, entry.origin, entry.observedAt, entry.status);
+                    .prepare(`INSERT INTO entries (stable_id, file, line, kind, key, text, trigger_phrases, importance, pinned, project, origin, observed_at, status, source)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(entry.stableId, entry.file, entry.line, entry.kind, entry.key, entry.text, JSON.stringify(entry.trigger), entry.importance, entry.pinned ? 1 : 0, entry.project, entry.origin, entry.observedAt, entry.status, entry.source ?? null);
                 if (this.fts)
                     this.db
                         .prepare("INSERT INTO entries_fts (stable_id, text) VALUES (?, ?);")
@@ -97,7 +103,7 @@ export class MemoryStore {
     }
     allEntries() {
         return this.db
-            .prepare("SELECT stable_id, file, line, kind, key, text, trigger_phrases, importance, pinned, project, origin, observed_at, status FROM entries ORDER BY observed_at ASC")
+            .prepare("SELECT stable_id, file, line, kind, key, text, trigger_phrases, importance, pinned, project, origin, observed_at, status, source FROM entries ORDER BY observed_at ASC")
             .all()
             .map((row) => {
             const value = row;
@@ -115,6 +121,7 @@ export class MemoryStore {
                 origin: value.origin ?? null,
                 observedAt: value.observed_at ?? null,
                 status: value.status ?? null,
+                source: value.source ?? null,
             };
         });
     }

package/dist/visibility.d.ts

@@ -0,0 +1,7 @@
+export type EntryVisibility = "team" | "personal";
+/**
+ * Usage-level visibility derived from the entry source. Team-prefixed skills,
+ * the GitLab collector, and spec-manage produce entries citable in
+ * team-facing artifacts; every other source stays personal-only.
+ */
+export declare function visibilityForSource(source: string | null | undefined): EntryVisibility;

package/dist/visibility.js

@@ -0,0 +1,13 @@
+const TEAM_CITABLE_SOURCES = ["gitlab", "spec-manage"];
+/**
+ * Usage-level visibility derived from the entry source. Team-prefixed skills,
+ * the GitLab collector, and spec-manage produce entries citable in
+ * team-facing artifacts; every other source stays personal-only.
+ */
+export function visibilityForSource(source) {
+    if (!source)
+        return "personal";
+    if (TEAM_CITABLE_SOURCES.includes(source) || source.startsWith("team-"))
+        return "team";
+    return "personal";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/memomatic",
-  "version": "1.0.0-dev.46.gfbe1e4c6992e",
+  "version": "1.0.0-dev.47.gcb218d104bc4",
   "description": "Personal learning memory for agents: tiered Markdown corpus, rebuildable index, dream sweep.",
   "homepage": "https://github.com/kisev/skills#readme",
   "bugs": {
@@ -34,7 +34,7 @@
     "pack:check": "node test/pack-allowlist.mjs"
   },
   "dependencies": {
-    "@kisev/safe-fs": "1.0.0-dev.46.gfbe1e4c6992e"
+    "@kisev/safe-fs": "1.0.0-dev.47.gcb218d104bc4"
   },
   "devDependencies": {
     "@types/node": "22.15.30",