Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

remember says when a fact is on no page

garrytanc3f437dc83ed
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf2b584c82..3649df9072 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,20 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**`remember` now says when a fact is on no page.** `remember` never creates a page. A fact saved for an entity whose page does not exist yet is stored in the database and recall returns it, but the reply read as if the fact had been written to that page, so an agent would report it as saved to a file. What is stored has not changed; the reply now tells the truth about it.
+
+### Itemized changes
+
+- The reply names a `page` only when the fact is on one. For an entity with no page it used to carry `page: "<the entity slug>"`, a page that does not exist; now the field is absent. A pending reply's `target.slug` follows the same rule.
+- Each `items` entry of a batch carries `persistence` and `write_through`, the same fields the single form returns. Before, a batch item gave no sign of whether it landed in a page file or in the database alone.
+- When the source has a checkout, the reason no file was written is `write_through.skipped: "entity_page_missing"`, in the reply and in the write receipt. It used to read `no_repo_configured`, which is false for such a source. A source with no checkout still reads `no_repo_configured`.
+- Where the brain's pages are in a Git repository, the reply adds one `entity_page_missing` notice per entity per session with the `put_page` call that creates the page. Once the page exists, the next maintenance cycle moves the facts saved for that entity into the page's Facts table and its file. A brain with no Git repository gets no notice, because there the database is the record.
+- `gbrain remember` prints `note: the entity has no page, so this fact is stored in the database only`, and a batch line ends `(no page: database only)`.
+- Docs: `docs/guides/entity-scoped-facts.md`, the `remember` section of `docs/mcp/TOOL_REFERENCE.md` and `docs/protocol/MEMORY_VERBS_v1.md` describe the reply. One behavior-change row discloses the reply change after an upgrade.
+- Tests: `test/remember-pageless-entity-gst2446.test.ts` runs on PGLite and Postgres against a Git checkout, a content folder with no Git and a source with no checkout, single and batch, through the operation handler and through MCP dispatch. It also pins that the fact reaches the page's Facts table and its committed file once the page is created.
+
## [0.60.675.0] - 2026-11-11
**Tool calls through native OpenAI models no longer fill every optional argument with a placeholder.** gbrain's tool loop (subagent jobs and SkillOpt rollouts) sends OpenAI models through the Responses API, and that API treats a tool definition with no `strict` field as strict: it marks every property required, so the model has to invent a value for each optional argument. A `get_page` call came back with a zero-line window and an empty byte range, which gbrain's own argument checks then refused. Native OpenAI tool definitions now say `strict: false`, so the schema's own `required` list holds and the model sends only the arguments it means. Anthropic, Google and the OpenAI-compatible providers (chat completions) send the same request as before. Reported and first fixed by @akinduroifedayo.
diff --git a/docs/guides/entity-scoped-facts.md b/docs/guides/entity-scoped-facts.md
index 78470c5740..0b9368dbbc 100644
--- a/docs/guides/entity-scoped-facts.md
+++ b/docs/guides/entity-scoped-facts.md
@@ -103,6 +103,17 @@ slug that has no page, still saves and still shows up in question recall, but
it has no file to live in: its only copy is in the database
([where your memory lives](where-your-memory-lives.md)). Create the page first.
+The reply tells you when that happened. A fact that landed on a page names it
+in `page`. A fact saved for an entity with no page has no `page`, and its
+`write_through` reads `{"written": false, "skipped": "entity_page_missing"}`;
+each item of an `items` batch says the same for itself. If the brain's pages
+are in a Git repository, the reply also carries an `entity_page_missing`
+notice with the `put_page` call that creates the page. Once the page exists,
+the next maintenance cycle (`gbrain dream`) moves the facts saved for that
+entity into the page's Facts table and its file. A brain with no Git
+repository gets no notice: there the database is the record, and the fact is
+as safe as everything else in it.
+
## Related
- [Entity recall](entity-recall.md): how gbrain resolves a name to an entity.
diff --git a/docs/mcp/TOOL_REFERENCE.md b/docs/mcp/TOOL_REFERENCE.md
index 52aad48ad1..97efa19965 100644
--- a/docs/mcp/TOOL_REFERENCE.md
+++ b/docs/mcp/TOOL_REFERENCE.md
@@ -372,7 +372,7 @@ MEMORY VERB (v1): retrieve saved facts/snippets — the protocol read verb. Filt
## `remember`
-MEMORY VERB (v1): save one fact to durable agent memory — the protocol write verb. provenance is REQUIRED (free text, e.g. "conversation 2026-06-12", "user said in chat", "import: notes.md"). Set `entity` whenever the fact is about a specific person/company/project — entity-scoped recall will not find it otherwise. ttl accepts duration shorthand ("30d", "12h") or an absolute ISO 8601 timestamp; ISO-8601 durations like "P30D" are rejected with a fix. visibility defaults to "world" (readable by every agent connected to this brain; pass "private" for local-CLI-only facts). A credential bound to a member, the brain owner's included, saves on its own member page as "private" by default; pass share: true to share a fact with everyone who reads the source. Response: branch on `status` (inserted|duplicate|superseded), never on `status_text` (human rendering only). On duplicate, `id` is the EXISTING fact's id. For bulk extraction from a raw transcript use extract_facts instead.
+MEMORY VERB (v1): save one fact to durable agent memory — the protocol write verb. provenance is REQUIRED (free text, e.g. "conversation 2026-06-12", "user said in chat", "import: notes.md"). Set `entity` whenever the fact is about a specific person/company/project — entity-scoped recall will not find it otherwise. ttl accepts duration shorthand ("30d", "12h") or an absolute ISO 8601 timestamp; ISO-8601 durations like "P30D" are rejected with a fix. visibility defaults to "world" (readable by every agent connected to this brain; pass "private" for local-CLI-only facts). A credential bound to a member, the brain owner's included, saves on its own member page as "private" by default; pass share: true to share a fact with everyone who reads the source. Response: branch on `status` (inserted|duplicate|superseded), never on `status_text` (human rendering only). On duplicate, `id` is the EXISTING fact's id. `page` names the page whose Facts table now holds the fact, and is absent when the fact is on no page: `remember` never creates a page, so a fact whose `entity` slug has no page is stored in the database only (`persistence: {mode: "database"}`, `write_through: {written: false, skipped: "entity_page_missing"}`) and still recalls. Each `items` entry carries its own `page`, `persistence` and `write_through`. Where the brain's pages are in a Git repository, that reply also carries an `entity_page_missing` notice with the `put_page` call that creates the page; the next maintenance cycle then moves the entity's facts into the page. For bulk extraction from a raw transcript use extract_facts instead.
| Parameter | Type | Guidance |
| --- | --- | --- |
diff --git a/docs/protocol/MEMORY_VERBS_v1.md b/docs/protocol/MEMORY_VERBS_v1.md
index fbd6a5adfd..0166e73838 100644
--- a/docs/protocol/MEMORY_VERBS_v1.md
+++ b/docs/protocol/MEMORY_VERBS_v1.md
@@ -408,6 +408,29 @@ Optional response fields; clients must ignore any they do not know.
caller is never told about an entity it cannot read: that case is `NO_ENTITY`.
- `hint: string` — present with `warnings`; names the `entity` input.
+#### remember: where the fact landed (additive)
+
+Optional response fields; clients must ignore any they do not know.
+
+- `page: string`: the page whose `## Facts` table now holds the fact. It is
+ absent when the fact is on no page: an `entity` slug that has no page, or a
+ fact with no entity on a source that cannot hold `memory/unattributed`.
+ `remember` never creates an entity page.
+- `visibility`: `world` or `private`, as saved.
+- `persistence: { mode }`: `filesystem` when the write changed a page file,
+ `database` when it changed the database alone.
+- `write_through: { written, skipped? }`: `skipped` says why no file was
+ written. `entity_page_missing`: the source has a checkout, but the entity
+ has no page to take the fact. `no_repo_configured`: the source has no
+ checkout, so the database is its record.
+
+A fact saved for an entity with no page is stored and recalled like any
+other. Where the source's pages are in Git, the reply also carries one
+`entity_page_missing` notice per entity per session, whose fix is the
+`put_page` call that creates the page; once the page exists, the next
+maintenance cycle moves the entity's facts into its Facts table and file. A
+brain with no Git repository gets no such notice.
+
#### remember items: several facts in one call (additive)
`items` (1 to 20) replaces `fact` for a batch, typically right before
@@ -426,7 +449,7 @@ writes nothing twice.
Response: `{ protocol_version, request_id, client_request_id?, items[], saved, failed, partial,
hints?, next? }`. Each `items[]` entry is a compact receipt `{ index,
-request_id, status, id?, entity_slug?, superseded_fact_id?, warnings?, valid_until?, state? }`
+request_id, status, id?, entity_slug?, page?, visibility?, persistence?, write_through?, superseded_fact_id?, warnings?, valid_until?, state? }`
(`state` and `retry_after_ms` only when the write is not yet committed), or
`{ index, request_id, status: "failed", error: { code, message, suggestion? } }`. Per-item hints
appear once in `hints`. `partial: true`: some saved; resend
diff --git a/llms-full.txt b/llms-full.txt
index d45061ba71..9416acbb49 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7955,6 +7955,29 @@ Optional response fields; clients must ignore any they do not know.
caller is never told about an entity it cannot read: that case is `NO_ENTITY`.
- `hint: string` — present with `warnings`; names the `entity` input.
+#### remember: where the fact landed (additive)
+
+Optional response fields; clients must ignore any they do not know.
+
+- `page: string`: the page whose `## Facts` table now holds the fact. It is
+ absent when the fact is on no page: an `entity` slug that has no page, or a
+ fact with no entity on a source that cannot hold `memory/unattributed`.
+ `remember` never creates an entity page.
+- `visibility`: `world` or `private`, as saved.
+- `persistence: { mode }`: `filesystem` when the write changed a page file,
+ `database` when it changed the database alone.
+- `write_through: { written, skipped? }`: `skipped` says why no file was
+ written. `entity_page_missing`: the source has a checkout, but the entity
+ has no page to take the fact. `no_repo_configured`: the source has no
+ checkout, so the database is its record.
+
+A fact saved for an entity with no page is stored and recalled like any
+other. Where the source's pages are in Git, the reply also carries one
+`entity_page_missing` notice per entity per session, whose fix is the
+`put_page` call that creates the page; once the page exists, the next
+maintenance cycle moves the entity's facts into its Facts table and file. A
+brain with no Git repository gets no such notice.
+
#### remember items: several facts in one call (additive)
`items` (1 to 20) replaces `fact` for a batch, typically right before
@@ -7973,7 +7996,7 @@ writes nothing twice.
Response: `{ protocol_version, request_id, client_request_id?, items[], saved, failed, partial,
hints?, next? }`. Each `items[]` entry is a compact receipt `{ index,
-request_id, status, id?, entity_slug?, superseded_fact_id?, warnings?, valid_until?, state? }`
+request_id, status, id?, entity_slug?, page?, visibility?, persistence?, write_through?, superseded_fact_id?, warnings?, valid_until?, state? }`
(`state` and `retry_after_ms` only when the write is not yet committed), or
`{ index, request_id, status: "failed", error: { code, message, suggestion? } }`. Per-item hints
appear once in `hints`. `partial: true`: some saved; resend
diff --git a/src/cli/remember-format.ts b/src/cli/remember-format.ts
index feab48ac8f..78152a460f 100644
--- a/src/cli/remember-format.ts
+++ b/src/cli/remember-format.ts
@@ -10,13 +10,14 @@ export function formatRememberResult(r: Record<string, any>, params: Record<stri
const lines = [`saved ${r.saved} of ${r.items.length} fact(s)${r.failed ? `, ${r.failed} failed` : ''}${r.pending ? `, ${r.pending} pending` : ''}`];
for (const item of r.items) {
lines.push(item.status === 'failed' ? ` items[${item.index}]: failed [${item.error?.code}] ${item.error?.message ?? ''}`
- : ` items[${item.index}]: ${item.status}${item.id !== undefined ? ` (fact #${item.id})` : ''}${item.entity_slug ? ` entity: ${item.entity_slug}` : ''}`);
+ : ` items[${item.index}]: ${item.status}${item.id !== undefined ? ` (fact #${item.id})` : ''}${item.entity_slug ? ` entity: ${item.entity_slug}` : ''}${item.write_through?.skipped === 'entity_page_missing' ? ' (no page: database only)' : ''}`);
}
if (r.next) lines.push(` next: ${r.next}`);
return lines.join('\n') + '\n';
}
const lines = [r.status_text || `${r.status} (fact #${r.id})`];
if (r.entity_slug) lines.push(` entity: ${r.entity_slug}${r.entity_inferred ? ' (inferred from mention)' : ''}`);
+ if (r.write_through?.skipped === 'entity_page_missing') lines.push(' note: the entity has no page, so this fact is stored in the database only');
if (r.valid_until) lines.push(` expires: ${r.valid_until}`);
if (r.degraded_dedup) lines.push(' note: no embedding provider — duplicate detection degraded');
if (params.visibility === 'private') lines.push(' note: private — local CLI recall only; not pushed into new agent sessions');
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 689d564c00..8ddd1c6fd7 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1529,6 +1529,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.673.0', id: 'autopilot_git_reconcile_gbra386', text: 'Autopilot now runs the new `gbrain sources git-reconcile` each tick: every source checkout on the host with an upstream fast-forwards when it is only behind, and one gbrain cloned for the source publishes its local commits (secret scan, rewrite check bound to the push, merged with the upstream in memory, never rebased or forced); a managed checkout goes through `gbrain sources refresh`, with its Git durability rule. A checkout gbrain did not clone keeps its local commits unless `sources.refresh_publish_diverged` is `true`, and a source with sync off is skipped. A refusal is logged and retried next tick. `autopilot.git_pull false` skips it; `sources.refresh_publish_diverged false` leaves local commits unpublished on every source, and `gbrain sources set-sync <id> off` leaves one source out (it also stops that source\'s automatic sync).' },
{ since: '0.60.673.0', id: 'unknown_drift_history_rescreen', text: 'A `file_drift` hold on a page with no import record that an earlier release held after comparing the page only with its file at the last synced commit is now screened once more on the next sync: when the page still holds one of its file\'s earlier committed versions (only Git changed since), the Git edit imports and the hold clears; otherwise the hold stays, unchanged, and is not screened again.' },
{ since: '0.60.673.0', id: 'refresh_abandon_members_gst1465', text: '`gbrain sources refresh --abandon` of a `recovery_required` refresh now also refuses when a member\'s managed sync imported or deleted pages after the refresh began, even with its `last_commit` still at the start commit (a pass its budget stopped), and refuses `sync_drain_lease_held` while a member\'s sync pass still holds its drain lease, so the database is never left ahead of the checkout. At a HEAD past the upstream commit it names `--resume` instead of a reset. Members synced to diverged lines, or to a commit git cannot place, now get their own refusal (merge those lines, or fetch the commit) instead of a fast-forward that `--resume` would refuse again, and the refusals name the revert route for a deliberate rollback. Writer status read off the owner host names no step for such a refresh.' },
+ { since: 'TBD', id: 'remember_pageless_reply_gst2446', text: 'A `remember` whose `entity` slug has no page still saves to the database, and its reply now says so: it no longer carries `page` (it used to name the entity slug, a page that does not exist), and where the source has a checkout `write_through.skipped` reads `entity_page_missing` instead of `no_repo_configured`, in the reply and in the write receipt. Each `items` entry of a batch now carries `persistence` and `write_through`, as the single form does. Where the source\'s pages are in Git, the reply adds one `entity_page_missing` notice with the `put_page` call that creates the page. What is stored is unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 3778dc8002..636193cffb 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -1022,6 +1022,7 @@ export const NOTICE_CODES = {
access_policy_pending: { kind: 'degraded', summary: 'A read touched a source whose folder rules are being narrowed or whose policy file does not validate: pages under the affected prefixes read as nobody until the brain host finishes it, so a missing page there is not proof the brain has nothing on it; the fix shows the policy state, then the host runs gbrain access resume --source <id> (database store); a git store finishes with gbrain sync --source <id> --no-pull.' },
degraded_dedup: { kind: 'info', summary: 'remember ran without an embedding provider, so only exact duplicates are detected.' },
facts_calibration_unmeasured: { kind: 'info', summary: 'recall --question ranked facts with semantic matching on an embedding model whose fact admission floors were never measured (`facts_calibration: {status: "unmeasured", model_key}`); a short facts list is weaker evidence of "nothing matched". Once per brain per session; the fix is the read-only `gbrain doctor --only fact_admission_floors --json`.' },
+ entity_page_missing: { kind: 'info', summary: 'remember saved a fact for an entity that has no page, on a source whose pages are in Git: the fact is stored in the database only (`write_through.skipped: entity_page_missing`, no `page` in the reply) until the page exists. The fix is the put_page call that creates the page; the next maintenance cycle then moves the entity\'s facts into its Facts table.' },
private_fact_not_pushed: { kind: 'info', summary: 'remember saved a private fact: only local CLI recall reads it, and session hooks never push it into a new agent session.' },
local_transcripts: { kind: 'info', summary: 'The brain host keeps recent session transcripts that page reads never return and this connection cannot read; the fix is the CLI read (`gbrain transcripts recent --json`).' },
synthesis_keyless: { kind: 'info', summary: 'think returned gathered evidence without synthesis because no chat-model key is configured (by design on a keyless brain).' },
diff --git a/src/core/interop-notices.ts b/src/core/interop-notices.ts
index 8eea56464c..121a7bb784 100644
--- a/src/core/interop-notices.ts
+++ b/src/core/interop-notices.ts
@@ -326,6 +326,27 @@ export function privateFactNotice(factId?: string | number): Notice {
};
}
+/**
+ * GST-2446: remember saved a fact for an entity that has no page, on a source whose pages are in Git. The fact is in
+ * the database alone until the page exists; the fix is the call that creates it. Once per entity per session.
+ */
+export function entityPageMissingNotice(sourceId: string, entitySlug: string): Notice {
+ return {
+ code: 'entity_page_missing',
+ kind: 'info',
+ dedupe_key: `${sourceId}\0${entitySlug}`,
+ why: `Entity ${entitySlug} has no page in source ${sourceId}, so a fact saved for it is stored in the database only: recall returns it, but it is on no page and in no file in Git. Say that when you report the save. To give it a file, create the page; the next maintenance cycle (gbrain dream) then moves every fact saved for ${entitySlug} into the page's Facts table and commits it.`,
+ fix: {
+ argv: ['gbrain', 'put', entitySlug],
+ mcp: { tool: 'put_page', arguments: { slug: entitySlug, content: '<content>' } },
+ inputs: [{ name: 'content', how: `The page as Markdown: frontmatter with type and title, then what is known about ${entitySlug}. On the CLI, pass it on stdin.` }],
+ consent: [], actor: 'agent', requires_exclusive: false,
+ why: `Creates the page ${entitySlug}, so its facts have a file.`,
+ verify: { argv: ['gbrain', 'get', entitySlug], mcp: { tool: 'get_page', arguments: { slug: entitySlug } } },
+ },
+ };
+}
+
// ── dispatch producer ──────────────────────────────────────────────────────
/** think's warning when the brain opted out of embedding and the question was never embedded. */
diff --git a/src/core/persistence/memory-mutations.ts b/src/core/persistence/memory-mutations.ts
index 2fefef60fb..eddb13deb7 100644
--- a/src/core/persistence/memory-mutations.ts
+++ b/src/core/persistence/memory-mutations.ts
@@ -17,7 +17,7 @@ import { emitFenceNotice, initializeLocalPersistence, requestPrincipalForContext
import { authorizeStoredRequest, submissionAuthority } from './authority.ts';
import { admitWrite, assertPageRequestIdentity, assertReplayIntent, getWriteRequest, intentDigest } from './journal.ts';
import { assertPersistenceAccepting, registerMutationPreparer, waitForWrite, writeResponse } from './service.ts';
-import { claimWorktree } from './ownership.ts';
+import { claimWorktree, getWorktreeBinding } from './ownership.ts';
import { resolveFactWriteTarget } from './fact-write-target.ts';
import { clientRequestIdOf, parseMutationPrecondition } from './preconditions.ts';
import { grantedWriteSource, writeGrantRefusal } from './write-grant.ts';
@@ -30,6 +30,8 @@ import { projectionEligibleSql } from '../eligibility/sql.ts';
import { resolveReadEligibility } from '../eligibility/policy.ts';
import { callerMember, factVisibilitySql, memberFactPage, memberPageIsOwn, memberPageNotOwned, memberPageSlug, ownMemberFactIds, scopePageIsShared, scopePageNotShared, SCOPE_PAGE_SLUG } from '../access/member-facts.ts';
import { perCallWriteSource } from '../access/attest-sources.ts';
+import { classifyGitCheckout } from '../git-checkout.ts';
+import { entityPageMissingNotice } from '../interop-notices.ts';
export { prepareMemoryMutation } from './memory-prepare.ts';
/** Only semantic appends without an explicit caller revision can be recomputed. */
@@ -123,6 +125,12 @@ async function planRememberTarget(ctx: OperationContext, sourceId: string, sourc
throw error;
}) : null;
if (unattributed && !snapshot && !target) fence = false;
+ // GST-2446: a named entity with no page keeps its fact out of every file. Where the source has a checkout the reason
+ // is the missing page, never a missing repository.
+ if (!fence && entitySlug !== null && writeThrough) {
+ const root = source.local_path || (sourceId === 'default' ? await ctx.engine.getConfig('sync.repo_path') : null);
+ authority.databaseOnlyReason = root || await getWorktreeBinding(ctx.engine, sourceId) ? 'entity_page_missing' : 'no_repo_configured';
+ }
let binding = target?.kind === 'publish' ? target.binding : null;
if (target?.kind === 'publish' && target.databaseOnlyReason) authority.databaseOnlyReason = target.databaseOnlyReason;
if (target?.kind === 'unbound') {
@@ -192,7 +200,7 @@ export async function submitRememberMutation(ctx: OperationContext, params: Reco
registerMutationPreparer('remember', prepareMemoryMutation);
const { visibility: _defaulted, ...withoutDefault } = params;
const sub = await submission(ctx, 'remember', params, opts.visibilityDefaulted ? withoutDefault : params);
- if (sub.prior) { const prior = sub.prior; const settled = await waitForWrite(ctx.engine, prior, ctx.config, waitMs ?? ctx.writeWaitMs); return rememberLanded(settled, throwIfHeld(withRememberTarget(prior, () => writeResponse(settled)))); }
+ if (sub.prior) { const prior = sub.prior; const settled = await waitForWrite(ctx.engine, prior, ctx.config, waitMs ?? ctx.writeWaitMs); return rememberLanded(ctx, settled, throwIfHeld(withRememberTarget(prior, () => writeResponse(settled)))); }
const { p, sourceId, principal, callerIntent, requestId, clientRequestId } = sub;
const [source] = await ctx.engine.executeRaw<RememberSource>(
"SELECT incarnation,archived,local_path,config->>'kind' AS kind FROM sources WHERE id=$1", [sourceId]);
@@ -244,13 +252,25 @@ export async function submitRememberMutation(ctx: OperationContext, params: Reco
const written = await waitForWrite(ctx.engine, row, ctx.config, waitMs ?? ctx.writeWaitMs);
const response = throwIfHeld(withRememberTarget(row, () => writeResponse(written)));
emitFenceNotice(ctx, response, row.slug);
- return rememberLanded(written, response);
+ return rememberLanded(ctx, written, response);
}
-/** GST-2243: every remember reply names the page the fact went to and who can recall it. */
-function rememberLanded<T>(row: WriteRequest, response: T): T {
- const visibility = (row.intent as { visibility?: unknown } | null)?.visibility;
- return { ...response, page: row.slug, ...(visibility === 'world' || visibility === 'private' ? { visibility } : {}) };
+/**
+ * GST-2243: every remember reply names the page the fact went to and who can recall it. GST-2446: a fact saved for an
+ * entity with no page is on no page, so the reply names none; where the source's pages are in Git, one notice gives
+ * the call that creates the page (a brain with no repository keeps the database as its record and is told nothing).
+ */
+async function rememberLanded<T extends Record<string, unknown>>(ctx: OperationContext, row: WriteRequest, response: T): Promise<T> {
+ const intent = row.intent as { visibility?: unknown; fence?: unknown; entity_slug?: unknown } | null;
+ if ((response.write_through as { skipped?: unknown } | undefined)?.skipped === 'entity_page_missing' && typeof intent?.entity_slug === 'string') {
+ const binding = await getWorktreeBinding(ctx.engine, row.source_id);
+ const root = binding?.local_path || (await ctx.engine.executeRaw<{ local_path: string | null }>('SELECT local_path FROM sources WHERE id=$1', [row.source_id]))[0]?.local_path
+ || (row.source_id === 'default' ? await ctx.engine.getConfig('sync.repo_path') : null);
+ if (binding?.canonical_git === true || binding?.git_durability === 'enabled' || root && classifyGitCheckout(root) === 'git') {
+ ctx.emitNotice?.(entityPageMissingNotice(row.source_id, intent.entity_slug));
+ }
+ }
+ return { ...response, ...(intent?.fence === true ? { page: row.slug } : {}), ...(intent?.visibility === 'world' || intent?.visibility === 'private' ? { visibility: intent.visibility } : {}) };
}
/**
@@ -262,7 +282,7 @@ function withRememberTarget<T>(row: WriteRequest, reply: () => T): T {
try { return reply(); } catch (error) {
if (error instanceof OperationError && error.writeRequest) {
const entity = (row.intent as { entity_slug?: unknown } | null)?.entity_slug;
- error.writeRequest.target = { slug: row.slug || null, entity_slug: typeof entity === 'string' ? entity : null };
+ error.writeRequest.target = { slug: (row.intent as { fence?: unknown } | null)?.fence === true && row.slug || null, entity_slug: typeof entity === 'string' ? entity : null };
}
throw error;
}
diff --git a/src/core/persistence/model.ts b/src/core/persistence/model.ts
index a8f7e70c19..2aef159700 100644
--- a/src/core/persistence/model.ts
+++ b/src/core/persistence/model.ts
@@ -31,7 +31,7 @@ export interface WriteAuthority {
attestedOp?: string;
/** GST-1113: the scope source an attested memory_write named instead of the principal's own; publication re-checks attest_sources. */
attestedSource?: string;
- databaseOnlyReason?: 'subagent_sandbox' | 'disabled_by_config' | 'no_repo_configured' | 'connector_database' | 'unbound_source' | 'overwrite_restore' | 'detached';
+ databaseOnlyReason?: 'subagent_sandbox' | 'disabled_by_config' | 'no_repo_configured' | 'connector_database' | 'unbound_source' | 'overwrite_restore' | 'detached' | 'entity_page_missing';
autoLinkTrusted?: boolean;
restrictedNamespace?: boolean;
sourceId: string;
diff --git a/src/core/remember-batch.ts b/src/core/remember-batch.ts
index 35356c9f53..4d68702702 100644
--- a/src/core/remember-batch.ts
+++ b/src/core/remember-batch.ts
@@ -110,6 +110,8 @@ export async function runRememberBatch(ctx: OperationContext, p: Record<string,
...(out?.id !== undefined ? { id: out.id } : {}),
...(out?.entity_slug !== undefined ? { entity_slug: out.entity_slug } : {}),
...(out?.page !== undefined ? { page: out.page } : {}), ...(out?.visibility !== undefined ? { visibility: out.visibility } : {}),
+ // GST-2446: where the item landed (a page file, or the database alone and why), as the single form reports it.
+ ...(out?.persistence !== undefined ? { persistence: out.persistence } : {}), ...(out?.write_through !== undefined ? { write_through: out.write_through } : {}),
...(out?.superseded_fact_id !== undefined ? { superseded_fact_id: out.superseded_fact_id } : {}), ...claimColumns(out),
...(Array.isArray(out?.warnings) && out.warnings.length ? { warnings: out.warnings } : {}),
...(out?.valid_until ? { valid_until: out.valid_until } : {}),
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index b7b4ef68d9..11f8f1b733 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -504,6 +504,7 @@ test/refresh-retry-hint-gst1582.test.ts
test/refresh-write-barrier.test.ts
test/remediation-manual-only.test.ts
test/remember-batch-entity-7432.test.ts
+test/remember-pageless-entity-gst2446.test.ts
test/remember-share-gst2243.test.ts
test/repair-apply-pending-6543.test.ts
test/repair-atom-fence-rows.test.ts
diff --git a/test/remember-pageless-entity-gst2446.test.ts b/test/remember-pageless-entity-gst2446.test.ts
new file mode 100644
index 0000000000..fd4f44752b
--- /dev/null
+++ b/test/remember-pageless-entity-gst2446.test.ts
@@ -0,0 +1,190 @@
+/**
+ * GST-2446: `remember` on an entity slug that has no page.
+ *
+ * 1. Protects: a fact saved for an entity with no page is stored in the database alone, and the reply says so:
+ * it names no `page`, the batch item carries the same `persistence` and `write_through` as the single form, the
+ * skip reason is `entity_page_missing` wherever the source has a checkout (never `no_repo_configured`), and on a
+ * source whose pages are in Git one `entity_page_missing` notice gives the `put_page` call that creates the page.
+ * Once the page exists, the extract_facts fence step moves the fact into its Facts table and its file.
+ * 2. Fails when: the reply names a page that does not exist, a batch hides where an item landed, a source with a
+ * checkout is told it has no repository, the caller is not told how to give the fact a file, or a brain with no
+ * Git repository (where the database is the record) is told to create one.
+ * 3. Existing coverage: test/remember-share-gst2243.test.ts pins `page` for facts that do land on a page;
+ * test/pathological/b-7-facts-pageless-entity.test.ts covers re-homing page-less facts.
+ * 4. Real seams: the coordinated write on PGLite and Postgres (DATABASE_URL), a managed checkout with and without
+ * Git, a source with no checkout, the operation handler as the local CLI calls it and MCP dispatch as a remote caller.
+ */
+import { describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import type { Notice } from '../src/core/agent-output.ts';
+import { operationsByName } from '../src/core/operations.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { fenceUnfencedFacts, planUnfencedFacts } from '../src/core/facts/unfenced-facts.ts';
+import { formatRememberResult } from '../src/cli/remember-format.ts';
+import { durableGitRepo, git } from './helpers/git-publication.ts';
+import { managedBrain, settleManagedGitEffects, type ManagedBrain } from './helpers/managed-brain.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+
+const PAGED = 'people/hana-example';
+const PAGELESS = 'notes/kitchen-remodel';
+const NOTICE = 'entity_page_missing';
+const page = (title: string) => `---\ntype: note\ntitle: ${title}\n---\n\nNotes about ${title}.\n`;
+const gitRepo = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
+
+interface Caller { ctx: OperationContext; notices: Notice[] }
+const caller = (base: OperationContext): Caller => {
+ const notices: Notice[] = [];
+ return { notices, ctx: { ...base, emitNotice: n => { if (n) notices.push(n); } } };
+};
+const call = (ctx: OperationContext, name: string, params: Record<string, unknown>) =>
+ operationsByName[name]!.handler(ctx, { request_id: randomUUID(), ...params }) as Promise<Record<string, any>>;
+const remember = (ctx: OperationContext, fact: string, entity: string) => call(ctx, 'remember', { fact, entity, provenance: 'chat 2026-11-11' });
+const batch = (ctx: OperationContext) => call(ctx, 'remember', { provenance: 'chat 2026-11-11', items: [
+ { fact: 'Hana Example cycles to work.', entity: PAGED }, { fact: 'The remodel budget is 40,000 USD.', entity: PAGELESS }] });
+async function overMcp(engine: BrainEngine, params: Record<string, unknown>) {
+ const out = await dispatchToolCall(engine, 'remember', { provenance: 'chat 2026-11-11', ...params }, { remote: true, transport: 'stdio', sourceId: 'default' });
+ expect(out.isError).not.toBe(true);
+ return { body: JSON.parse(out.content[0]!.text) as Record<string, any>, blocks: out.content.slice(1).map(block => block.text) };
+}
+const putPage = (ctx: OperationContext, slug: string, title: string) => call(ctx, 'put_page', { slug, content: page(title) });
+
+for (const backend of testBackends()) describe(`[${backend}] remember on an entity with no page (GST-2446)`, () => {
+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
+ /** A managed brain whose default source is a checkout: a Git repository (pages are committed) or a plain content folder. */
+ const checkout = (kind: 'git' | 'folder', run: (brain: ManagedBrain) => Promise<void>) =>
+ managedBrain(async brain => { await putPage(brain.ctx, PAGED, 'Hana Example'); await run(brain); }, { databaseUrl, ...(kind === 'git' ? { setup: gitRepo } : {}) });
+ /** A brain whose source has no checkout at all: the database is the record. */
+ async function noCheckout(run: (brain: { engine: BrainEngine; ctx: OperationContext }) => Promise<void>): Promise<void> {
+ let engine: BrainEngine; let close: () => Promise<void>;
+ if (backend === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(databaseUrl!));
+ else { const pglite = new PGLiteEngine(); await pglite.connect({ engine: 'pglite' } as never); await pglite.initSchema(); engine = pglite; close = () => pglite.disconnect(); }
+ try {
+ const ctx: OperationContext = { engine, config: { engine: engine.kind, embedding_disabled: true } as never, sourceId: 'default', remote: false, dryRun: false,
+ logger: { info() {}, warn() {}, error() {} } };
+ await putPage(ctx, PAGED, 'Hana Example');
+ await run({ engine, ctx });
+ } finally { await disposePersistenceConsumer(engine); await close(); }
+ }
+
+ test('the reply names a page only when the fact is on one', () => checkout('git', async ({ engine, ctx }) => {
+ const pageless = await remember(ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ expect(pageless).toMatchObject({ status: 'inserted', entity_slug: PAGELESS, visibility: 'world' });
+ expect(pageless).not.toHaveProperty('page');
+ expect(await engine.executeRaw('SELECT 1 FROM pages WHERE slug=$1', [PAGELESS])).toHaveLength(0);
+ expect(await remember(ctx, 'Hana Example prefers tea.', PAGED)).toMatchObject({ status: 'inserted', page: PAGED });
+ const { items } = await batch(ctx);
+ expect(items[0]).toMatchObject({ status: 'inserted', entity_slug: PAGED, page: PAGED });
+ expect(items[1]).toMatchObject({ status: 'inserted', entity_slug: PAGELESS });
+ expect(items[1]).not.toHaveProperty('page');
+ const mcp = await overMcp(engine, { fact: 'The remodel contractor is acme-example.', entity: PAGELESS });
+ expect(mcp.body).toMatchObject({ status: 'inserted', entity_slug: PAGELESS });
+ expect(mcp.body).not.toHaveProperty('page');
+ }), 180_000);
+
+ test('a batch item carries the same persistence and write_through as the single form', () => checkout('git', async ({ ctx }) => {
+ const { items } = await batch(ctx);
+ expect(items[0].persistence).toMatchObject({ mode: 'filesystem', file_written: true });
+ expect(items[0].write_through).toEqual({ written: true });
+ const single = await remember(ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ expect(items[1].persistence).toEqual(single.persistence);
+ expect(items[1].write_through).toEqual(single.write_through);
+ expect(items[1].persistence).toEqual({ mode: 'database' });
+ }), 180_000);
+
+ test('the skip reason says the entity has no page, in the reply, the batch and the receipt', () => checkout('git', async ({ ctx }) => {
+ const single = await remember(ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ expect(single.write_through).toEqual({ written: false, skipped: NOTICE });
+ expect((await batch(ctx)).items[1].write_through).toEqual({ written: false, skipped: NOTICE });
+ const receipt = await call(ctx, 'get_write_request', { request_id: single.request_id });
+ expect(receipt.outcome.write_through).toEqual({ written: false, skipped: NOTICE });
+ expect(formatRememberResult(single)).toContain('note: the entity has no page, so this fact is stored in the database only');
+ expect(formatRememberResult(await batch(ctx))).toContain(`entity: ${PAGELESS} (no page: database only)`);
+ }), 180_000);
+
+ test('on a Git checkout the reply says how to give the fact a file: one notice with the put_page call', () => checkout('git', async ({ engine, ctx }) => {
+ const local = caller(ctx);
+ const single = await remember(local.ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ const [notice] = local.notices.filter(n => n.code === NOTICE);
+ expect(notice).toMatchObject({ kind: 'info', dedupe_key: `default\0${PAGELESS}` });
+ expect(notice!.why).toContain(`${PAGELESS} has no page`);
+ expect(notice!.why).toContain('database only');
+ expect(notice!.fix).toMatchObject({ actor: 'agent', consent: [], argv: ['gbrain', 'put', PAGELESS],
+ mcp: { tool: 'put_page', arguments: { slug: PAGELESS, content: '<content>' } }, inputs: [{ name: 'content' }],
+ verify: { mcp: { tool: 'get_page', arguments: { slug: PAGELESS } } } });
+ // A fact that lands on a page carries no such notice.
+ const paged = caller(ctx);
+ await remember(paged.ctx, 'Hana Example prefers tea.', PAGED);
+ expect(paged.notices.map(n => n.code)).not.toContain(NOTICE);
+ // A batch says it once per entity, and a replayed request says it again.
+ const both = caller(ctx);
+ await batch(both.ctx);
+ expect(both.notices.filter(n => n.code === NOTICE)).toHaveLength(1);
+ const replay = caller(ctx);
+ await call(replay.ctx, 'remember', { fact: 'The kitchen remodel starts in March.', entity: PAGELESS, provenance: 'chat 2026-11-11', request_id: single.request_id });
+ expect(replay.notices.filter(n => n.code === NOTICE)).toHaveLength(1);
+ // Over MCP the notice is a text block after the body, with the call to make (shown once per entity per session, so this entity is new).
+ const unseen = `notes/garden-plan-${randomUUID().slice(0, 8)}`;
+ const mcp = await overMcp(engine, { fact: 'The garden plan adds two raised beds.', entity: unseen });
+ const block = mcp.blocks.find(text => text.startsWith(`[gbrain notice ${NOTICE} kind=info]`));
+ expect(block).toBeDefined();
+ expect(block).toContain(`fix: put_page {"slug":"${unseen}","content":"<content>"}`);
+ expect(block).toContain('next: run');
+ const inBatch = `notes/pond-plan-${randomUUID().slice(0, 8)}`;
+ const mcpBatch = await overMcp(engine, { items: [{ fact: 'Hana Example keeps bees.', entity: PAGED }, { fact: 'The pond plan needs a liner.', entity: inBatch }] });
+ expect(mcpBatch.body.items[1].write_through).toEqual({ written: false, skipped: NOTICE });
+ expect(mcpBatch.blocks.filter(text => text.startsWith(`[gbrain notice ${NOTICE} kind=info]`) && text.includes(inBatch))).toHaveLength(1);
+ }), 180_000);
+
+ test('once the page exists, the extract_facts fence step moves the fact into its Facts table and its file', () => checkout('git', async ({ engine, ctx, root }) => {
+ const saved = await remember(ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ await putPage(ctx, PAGELESS, 'Kitchen remodel');
+ const outcome = await fenceUnfencedFacts(engine, await planUnfencedFacts(engine, { sourceId: 'default' }));
+ expect(outcome).toMatchObject({ fenced: 1, fenced_slugs: [PAGELESS], failed_pages: [] });
+ const [fact] = await engine.executeRaw<{ row_num: number | null; source_markdown_slug: string | null; expired_at: unknown }>(
+ 'SELECT row_num, source_markdown_slug, expired_at FROM facts WHERE id=$1', [Number(saved.id)]);
+ expect(fact).toMatchObject({ row_num: 1, source_markdown_slug: PAGELESS, expired_at: null });
+ await settleManagedGitEffects(engine);
+ expect(readFileSync(join(root, `${PAGELESS}.md`), 'utf8')).toContain('| 1 | The kitchen remodel starts in March. |');
+ expect(git(root, 'show', `HEAD:${PAGELESS}.md`)).toContain('The kitchen remodel starts in March.');
+ }), 180_000);
+
+ test('a content folder with no Git: the reason is the missing page, and nothing says the fact is at risk', () => checkout('folder', async ({ engine, ctx }) => {
+ const local = caller(ctx);
+ const single = await remember(local.ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ expect(single).toMatchObject({ status: 'inserted', persistence: { mode: 'database' }, write_through: { written: false, skipped: NOTICE } });
+ expect(single).not.toHaveProperty('page');
+ const { items } = await batch(local.ctx);
+ expect(items[1]).toMatchObject({ persistence: { mode: 'database' }, write_through: { written: false, skipped: NOTICE } });
+ expect(items[1]).not.toHaveProperty('page');
+ expect(local.notices.map(n => n.code)).not.toContain(NOTICE);
+ const mcp = await overMcp(engine, { fact: 'The remodel contractor is acme-example.', entity: PAGELESS });
+ expect(mcp.blocks.join('\n')).not.toContain(NOTICE);
+ }), 180_000);
+
+ test('a source with no checkout: the database is the record, so the reply asks for nothing', () => noCheckout(async ({ engine, ctx }) => {
+ const local = caller(ctx);
+ const single = await remember(local.ctx, 'The kitchen remodel starts in March.', PAGELESS);
+ expect(single).toMatchObject({ status: 'inserted', persistence: { mode: 'database' }, write_through: { written: false, skipped: 'no_repo_configured' } });
+ expect(single).not.toHaveProperty('page');
+ expect(formatRememberResult(single)).not.toContain('no page');
+ // A fact that lands on a database-only page still names it.
+ expect(await remember(local.ctx, 'Hana Example prefers tea.', PAGED)).toMatchObject({ page: PAGED, persistence: { mode: 'database' } });
+ const { items } = await batch(local.ctx);
+ expect(items[0]).toMatchObject({ page: PAGED, persistence: { mode: 'database' }, write_through: { written: false, skipped: 'no_repo_configured' } });
+ expect(items[1]).toMatchObject({ persistence: { mode: 'database' }, write_through: { written: false, skipped: 'no_repo_configured' } });
+ expect(items[1]).not.toHaveProperty('page');
+ expect(local.notices.map(n => n.code)).not.toContain(NOTICE);
+ const mcp = await overMcp(engine, { fact: 'The remodel contractor is acme-example.', entity: PAGELESS });
+ expect(mcp.body).not.toHaveProperty('page');
+ expect(mcp.body.write_through).toEqual({ written: false, skipped: 'no_repo_configured' });
+ expect(mcp.blocks.join('\n')).not.toContain(NOTICE);
+ expect(mcp.blocks.join('\n')).not.toContain('put_page');
+ }), 180_000);
+});