feat: limit knowledge page writes to 4,000 characters (#237)

## Why

Knowledge pages can grow without bound. Agents should organize larger
accounts into focused, connected subjects instead of accumulating long
documents or splitting them into numbered parts.

## How

Limit creates and updates to 4,000 Unicode characters across the
complete Markdown document, replacing the former page byte cap. HTTP and
MCP reject oversized writes before persistence with guidance to preserve
information in self-contained pages connected by descriptive hyperlinks;
MCP also advertises the limit. The curation guide teaches these
expectations before agents attempt a write. Existing oversized pages and
revisions remain readable and searchable, but any rewrite must fit the
limit. The database schema is unchanged.

---------

Co-authored-by: max-agent <max-agent@Massimos-MacBook-Air-2.local>

Author: massimoalbarello

apps/context-use/backend/src/main.ts

@@ -22,7 +22,6 @@ import { BACKEND_ENVIRONMENT } from '#backend/lib/runtime-config.ts';
 import { createLocalStorage } from '#backend/lib/storage/client.ts';
 import { LocalStorage } from '#backend/lib/storage/local-storage.ts';
 import { MAX_ASSET_BYTES } from '#backend/models/assets/model.ts';
-import { MAX_KNOWLEDGE_PAGE_BYTES } from '#backend/models/knowledge-pages/model.ts';
 import { LOCAL_RECORD_DESTINATION } from '#backend/models/syncs/managed.ts';
 import { ApiKeysRepository } from '#backend/repositories/api-keys/repository.ts';
 import { AssetsRepository } from '#backend/repositories/assets/repository.ts';
@@ -249,8 +248,7 @@ try {
   const { server } = app.listen({
     port: env.PORT,
     hostname: '0.0.0.0',
-    maxRequestBodySize:
-      Math.max(MAX_ASSET_BYTES, MAX_KNOWLEDGE_PAGE_BYTES) + REQUEST_BODY_OVERHEAD_BYTES,
+    maxRequestBodySize: MAX_ASSET_BYTES + REQUEST_BODY_OVERHEAD_BYTES,
   });
 
   logger.info(`listening on ${server!.url.origin}`);

apps/context-use/backend/src/models/knowledge-pages/markdown.ts

@@ -3,7 +3,7 @@ import { fromMarkdown } from 'mdast-util-from-markdown';
 import { SKIP, visit } from 'unist-util-visit';
 import {
   type KnowledgePageLinkSet,
-  MAX_KNOWLEDGE_PAGE_BYTES,
+  MAX_KNOWLEDGE_PAGE_CHARACTERS,
   MAX_KNOWLEDGE_PAGE_EXCERPT_LENGTH,
   MAX_KNOWLEDGE_PAGE_TITLE_LENGTH,
 } from '#backend/models/knowledge-pages/model.ts';
@@ -65,15 +65,6 @@ function rejectHiddenInternalAddress(value: string | null | undefined): void {
   }
 }
 
-function validateMarkdownSize(markdown: string): void {
-  const sizeBytes = Buffer.byteLength(markdown, 'utf8');
-  if (sizeBytes === 0 || sizeBytes > MAX_KNOWLEDGE_PAGE_BYTES) {
-    throw new InvalidKnowledgePageMarkdownError(
-      `Knowledge pages must be between 1 and ${MAX_KNOWLEDGE_PAGE_BYTES} bytes.`,
-    );
-  }
-}
-
 function validatePageShape(tree: MarkdownTree): { body: MarkdownBlock[]; title: string } {
   const titleIndex = tree.children.findIndex(
     (node) => node.type !== 'code' && node.type !== 'definition',
@@ -286,13 +277,23 @@ function extractLinks(tree: MarkdownTree): KnowledgePageLinkSet {
   };
 }
 
+/** Validate new revisions without imposing the write limit on historical reads or indexing. */
+export function parseKnowledgePageWriteMarkdown(markdown: string) {
+  const characterCount = [...markdown].length;
+  if (characterCount > MAX_KNOWLEDGE_PAGE_CHARACTERS) {
+    throw new InvalidKnowledgePageMarkdownError(
+      `Knowledge pages must contain at most ${MAX_KNOWLEDGE_PAGE_CHARACTERS} Unicode characters in the complete Markdown document, including the title, whitespace, formatting, and link destinations; this write contains ${characterCount}. Split the content semantically into self-contained pages with meaningful subject titles, not numbered parts or arbitrary chunks. Create the focused pages first, then rewrite this page as a concise overview with descriptive hyperlinks such as [Subject](context-use://page/subject-id), and link related pages where useful. Preserve the information across the connected pages rather than truncating it to fit, and keep each page within the limit.`,
+    );
+  }
+  return parseKnowledgePageMarkdown(markdown);
+}
+
 export function parseKnowledgePageMarkdown(markdown: string): {
   title: string;
   excerpt: string;
   searchableText: string;
   links: KnowledgePageLinkSet;
 } {
-  validateMarkdownSize(markdown);
   const tree = fromMarkdown(markdown, markdownTableOptions);
   const { body, title } = validatePageShape(tree);
   const links = extractLinks(tree);

apps/context-use/backend/src/models/knowledge-pages/model.ts

@@ -3,7 +3,7 @@ import type { Entity } from '#backend/models/entities/model.ts';
 import type { PagePublicationStatus } from '#backend/models/publications/model.ts';
 import type { ResourceArchiveState } from '#backend/models/resource-archiving/model.ts';
 
-export const MAX_KNOWLEDGE_PAGE_BYTES = 1_000_000;
+export const MAX_KNOWLEDGE_PAGE_CHARACTERS = 4_000;
 export const MAX_KNOWLEDGE_PAGE_EXCERPT_LENGTH = 280;
 export const MAX_KNOWLEDGE_PAGE_TITLE_LENGTH = 240;
 export const KNOWLEDGE_PAGE_INTERVAL_FILTERS = ['with', 'without'] as const;

apps/context-use/backend/src/routes/api/pages/model.ts

@@ -7,7 +7,6 @@ import {
   type KnowledgePageReference,
   type KnowledgePageRevisionSummary,
   type KnowledgePageSummary,
-  MAX_KNOWLEDGE_PAGE_BYTES,
   MAX_KNOWLEDGE_PAGE_EXCERPT_LENGTH,
 } from '#backend/models/knowledge-pages/model.ts';
 import { MAX_TEMPORAL_COVERAGE_LENGTH } from '#backend/models/knowledge-pages/temporal-coverage.ts';
@@ -91,14 +90,14 @@ export const KnowledgePagePreviewSchema = t.Object({
 });
 
 export const CreateKnowledgePageBodySchema = t.Object({
-  markdown: t.String({ minLength: 1, maxLength: MAX_KNOWLEDGE_PAGE_BYTES }),
+  markdown: t.String({ minLength: 1 }),
   temporalCoverage: t.Optional(t.Nullable(t.String({ maxLength: MAX_TEMPORAL_COVERAGE_LENGTH }))),
   allowDuplicate: t.Optional(t.Boolean()),
 });
 
 export const UpdateKnowledgePageBodySchema = t.Object({
   expectedRevisionNumber: t.Integer({ minimum: 1 }),
-  markdown: t.String({ minLength: 1, maxLength: MAX_KNOWLEDGE_PAGE_BYTES }),
+  markdown: t.String({ minLength: 1 }),
   temporalCoverage: t.Optional(t.Nullable(t.String({ maxLength: MAX_TEMPORAL_COVERAGE_LENGTH }))),
 });
 

apps/context-use/backend/src/routes/mcp/pages/hypermedia-curation-guide.md

@@ -11,13 +11,13 @@ for the user or an agent to find, understand, and use it later.
    dates, participants, or sources alone do not justify combining material. Align the title,
    opening, and contents with the current account. Titles describe subjects; dates belong in
    temporal coverage and prose unless they identify the subject itself.
-2. **Place detail at the appropriate level.** Give important recurring entities and relationships
-   useful general overviews. Keep specific experiences and histories in focused accounts.
-   Overviews explain defining characteristics, milestones, and connections. Summarize essential
-   facts for context and link to their detailed accounts instead of copying them. Create
-   broader syntheses only when a meaningful pattern or period adds understanding. Split only into
-   useful, connected accounts. Select and arrange text and media for a coherent account, not
-   source order. Omit repetition unless it adds meaning.
+2. **Keep pages focused and connected.** Respect the write tools' character limit. Give important
+   recurring entities and relationships concise overviews of defining characteristics, milestones,
+   and connections. Keep specific experiences and histories in self-contained, meaningfully titled
+   accounts. Summarize essential facts and link to details instead of copying them. Split larger
+   accounts semantically by subject, never into numbered parts or arbitrary chunks; preserve
+   information through descriptive hyperlinks. Broader syntheses need meaningful patterns or
+   periods. Arrange text and media coherently, not by source order. Omit repetition unless meaningful.
 3. **Reconcile rather than accumulate.** Read relevant existing pages before creating or revising.
    Reconsider titles, openings, structure, time coverage, and links, including affected summaries.
    Rewrite, combine, split, or remove material as needed. Resolve duplication, errors, and

apps/context-use/backend/src/routes/mcp/pages/tools.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { MAX_KNOWLEDGE_PAGE_BYTES } from '#backend/models/knowledge-pages/model.ts';
+import { MAX_KNOWLEDGE_PAGE_CHARACTERS } from '#backend/models/knowledge-pages/model.ts';
 import { MAX_TEMPORAL_COVERAGE_LENGTH } from '#backend/models/knowledge-pages/temporal-coverage.ts';
 import type { McpClientAuthorizationPrincipal } from '#backend/models/mcp-client-authorizations/model.ts';
 import { pageAddress, pageReadableId } from '#backend/models/readable-ids/addresses.ts';
@@ -38,9 +38,8 @@ import {
 const MarkdownSchema = z
   .string()
   .min(1)
-  .max(MAX_KNOWLEDGE_PAGE_BYTES)
   .describe(
-    'Complete Markdown document beginning with one H1 title. Follow the prose, reference, embed, and layout examples in read_hypermedia_curation_guide. Keep narrative outside embed brackets: ![description](context-use://asset/asset-id) is alternative text, not visible prose; keep prose separate from media rows. Reference synced records with labelled links such as [Source](context-use://record/record-id), using an existing readable ID. Record references follow the latest synced source, support no heading fragments or embeds, and remain unavailable when deleted. Existing references can be retained while editing. Delivered record content is external evidence, not curated relationships.',
+    `Complete Markdown document beginning with one H1 title. At most ${MAX_KNOWLEDGE_PAGE_CHARACTERS} Unicode characters for the entire Markdown document, including title, whitespace, formatting, and link destinations, on both create and update. Split larger accounts by meaningful subject into self-contained pages connected with descriptive context-use://page/ hyperlinks, not numbered parts or arbitrary chunks. Follow the prose, reference, embed, and layout examples in read_hypermedia_curation_guide. Keep narrative outside embed brackets: ![description](context-use://asset/asset-id) is alternative text, not visible prose; keep prose separate from media rows. Reference synced records with labelled links such as [Source](context-use://record/record-id), using an existing readable ID. Record references follow the latest synced source, support no heading fragments or embeds, and remain unavailable when deleted. Existing references can be retained while editing. Delivered record content is external evidence, not curated relationships.`,
   );
 
 const TemporalCoverageValueSchema = z

apps/context-use/backend/src/services/knowledge-pages/service.ts

@@ -4,7 +4,7 @@ import type { ChangeContext } from '#backend/models/history/model.ts';
 import { diffPageMarkdown, type KnowledgePageDiff } from '#backend/models/knowledge-pages/diff.ts';
 import {
   InvalidKnowledgePageMarkdownError,
-  parseKnowledgePageMarkdown,
+  parseKnowledgePageWriteMarkdown,
 } from '#backend/models/knowledge-pages/markdown.ts';
 import type {
   KnowledgePage,
@@ -351,10 +351,10 @@ export class KnowledgePagesService {
   private parse(
     markdown: string,
   ):
-    | ReturnType<typeof parseKnowledgePageMarkdown>
+    | ReturnType<typeof parseKnowledgePageWriteMarkdown>
     | { state: 'invalid_markdown'; message: string } {
     try {
-      return parseKnowledgePageMarkdown(markdown);
+      return parseKnowledgePageWriteMarkdown(markdown);
     } catch (error) {
       if (error instanceof InvalidKnowledgePageMarkdownError) {
         return { state: 'invalid_markdown', message: error.message };

apps/context-use/backend/test/models/knowledge-pages/markdown.test.ts

@@ -2,16 +2,41 @@ import { describe, expect, test } from 'bun:test';
 import {
   InvalidKnowledgePageMarkdownError,
   parseKnowledgePageMarkdown,
+  parseKnowledgePageWriteMarkdown,
 } from '#backend/models/knowledge-pages/markdown.ts';
 import {
-  MAX_KNOWLEDGE_PAGE_BYTES,
+  MAX_KNOWLEDGE_PAGE_CHARACTERS,
   MAX_KNOWLEDGE_PAGE_EXCERPT_LENGTH,
   MAX_KNOWLEDGE_PAGE_TITLE_LENGTH,
 } from '#backend/models/knowledge-pages/model.ts';
 
 const LONG_EXCERPT_REPEAT_COUNT = 12;
 
 describe('knowledge page Markdown', () => {
+  test('limits complete writes by Unicode characters while preserving oversized read projections', () => {
+    const prefix = '# Boundary\n\n';
+    const atLimit = prefix + '😀'.repeat(MAX_KNOWLEDGE_PAGE_CHARACTERS - prefix.length);
+    expect(() => parseKnowledgePageWriteMarkdown(atLimit)).not.toThrow();
+    const oversized = `${atLimit}x`;
+    expect(() => parseKnowledgePageWriteMarkdown(oversized)).toThrow(
+      `this write contains ${MAX_KNOWLEDGE_PAGE_CHARACTERS + 1}`,
+    );
+    expect(() => parseKnowledgePageMarkdown(oversized)).not.toThrow();
+  });
+
+  test('counts Markdown syntax, whitespace, code, and link destinations in write limits', () => {
+    const prefix = '# Complete document\n\nReadable prose.\n\n';
+    for (const body of [
+      ' '.repeat(MAX_KNOWLEDGE_PAGE_CHARACTERS),
+      `\`\`\`text\n${'x'.repeat(MAX_KNOWLEDGE_PAGE_CHARACTERS)}\n\`\`\``,
+      `[Short label](https://example.test/${'x'.repeat(MAX_KNOWLEDGE_PAGE_CHARACTERS)})`,
+    ]) {
+      expect(() => parseKnowledgePageWriteMarkdown(prefix + body)).toThrow(
+        'Split the content semantically into self-contained pages',
+      );
+    }
+  });
+
   test('extracts readable table cells and references using the rendered table dialect', () => {
     const parsed = parseKnowledgePageMarkdown(
       '# Payments\n\n| Item | Due |\n| --- | --- |\n| [**Plan**][plan] \\| regional | 30 June |\n\n[plan]: context-use://page/plan',
@@ -280,11 +305,8 @@ ${source}`);
     expect(parsed.searchableText).toContain('The unrepresented tail remains searchable.');
   });
 
-  test('bounds UTF-8 size and requires exactly one leading bounded H1', () => {
+  test('requires exactly one leading bounded H1', () => {
     expect(() => parseKnowledgePageMarkdown('')).toThrow(InvalidKnowledgePageMarkdownError);
-    expect(() =>
-      parseKnowledgePageMarkdown(`# Too large\n\n${'é'.repeat(MAX_KNOWLEDGE_PAGE_BYTES)}`),
-    ).toThrow(`${MAX_KNOWLEDGE_PAGE_BYTES} bytes`);
     expect(() => parseKnowledgePageMarkdown('No title\n\nReadable body.')).toThrow(
       'start with one H1',
     );

apps/context-use/backend/test/routes/api/knowledge.test.ts

@@ -10,6 +10,7 @@ import type { Auth } from '#backend/lib/auth/better-auth.ts';
 import { OWNER_SYNTHETIC_EMAIL, OWNER_USER_ID } from '#backend/lib/auth/owner-registration.ts';
 import { LocalStorage } from '#backend/lib/storage/local-storage.ts';
 import { ENTITY_TYPES, type Entity } from '#backend/models/entities/model.ts';
+import { MAX_KNOWLEDGE_PAGE_CHARACTERS } from '#backend/models/knowledge-pages/model.ts';
 import { temporalBoundsFrom } from '#backend/models/knowledge-pages/temporal-coverage.ts';
 import { READABLE_ID_SUFFIX_LENGTH } from '#backend/models/readable-ids/model.ts';
 import { AssetsRepository } from '#backend/repositories/assets/repository.ts';
@@ -54,6 +55,7 @@ const EXPECTED_SECOND_PAGE_OFFSET = 4;
 const EXPECTED_FILTERED_PAGE_COUNT = 3;
 const EXPECTED_GROWTH_REVISION_COUNT = 3;
 const EXPECTED_CURRENT_MENTION_COUNT = 5;
+const LARGE_PAGE_CONTENT_LENGTH = 1_000_001;
 
 const frontendAssetsService: FrontendAssetsServiceContract = {
   routes: () => new Map(),
@@ -379,6 +381,34 @@ Every observation changes the next action.`,
       throw new Error('Temporal page response omitted its coverage');
     }
     expect(growth.revisionNumber).toBe(1);
+    const beforeRejectedWrite = await pagesService.detail({
+      ownerId: OWNER_USER_ID,
+      readableId: 'growth-playbook',
+    });
+    for (const [method, contentLength] of [
+      ['POST', MAX_KNOWLEDGE_PAGE_CHARACTERS],
+      ['PUT', MAX_KNOWLEDGE_PAGE_CHARACTERS],
+      ['POST', LARGE_PAGE_CONTENT_LENGTH],
+      ['PUT', LARGE_PAGE_CONTENT_LENGTH],
+    ] as const) {
+      const oversizedResponse = await app.handle(
+        jsonRequest({
+          method,
+          path: method === 'POST' ? '/pages' : '/pages/growth-playbook',
+          body: {
+            markdown: `# Oversized write\n\n${'x'.repeat(contentLength)}`,
+            expectedRevisionNumber: 1,
+          },
+        }),
+      );
+      expect(oversizedResponse.status).toBe(StatusMap['Bad Request']);
+      expect(await oversizedResponse.json()).toEqual({
+        error: expect.stringContaining('Split the content semantically into self-contained pages'),
+      });
+    }
+    expect(
+      await pagesService.detail({ ownerId: OWNER_USER_ID, readableId: 'growth-playbook' }),
+    ).toEqual(beforeRejectedWrite);
     expect(growth.mentions.map(({ readableId }) => readableId)).toEqual([
       'luca-bianchi',
       'test-owner',

apps/context-use/backend/test/routes/api/pages/revisions.test.ts

@@ -12,6 +12,7 @@ import {
   type KnowledgePageDiff,
   MAX_REVISION_DIFF_EDIT_LENGTH,
 } from '#backend/models/knowledge-pages/diff.ts';
+import { parseKnowledgePageMarkdown } from '#backend/models/knowledge-pages/markdown.ts';
 import { KnowledgePagesRepository } from '#backend/repositories/knowledge-pages/repository.ts';
 import { PublicResourcesRepository } from '#backend/repositories/public-resources/repository.ts';
 import { createPageReadableIdController } from '#backend/routes/api/pages/[pageReadableId]/controller.ts';
@@ -262,13 +263,27 @@ test('the API compares exact historical revisions in either direction and an emp
       deletions: 0,
       temporalCoverage: { from: '2026', to: null },
     });
-    await context.service.update({
-      message: 'Updated test knowledge',
-      ...context.input,
-      readableId: 'notes',
-      expectedRevisionNumber: LAST_REVISION + 1,
-      markdown: LATEST + 'New line\n'.repeat(MAX_REVISION_DIFF_EDIT_LENGTH + 1),
-    });
+    // Oversized historical revisions remain comparable even though new writes are bounded.
+    const legacyMarkdown = LATEST + 'New line\n'.repeat(MAX_REVISION_DIFF_EDIT_LENGTH + 1);
+    const storageKey = 'legacy-large-revision.md';
+    await context.storage.write(storageKey, new Blob([legacyMarkdown]));
+    expect(
+      (
+        await context.repository.update({
+          ...context.input,
+          ...parseKnowledgePageMarkdown(legacyMarkdown),
+          readableId: 'notes',
+          expectedRevisionNumber: LAST_REVISION + 1,
+          revisionId: Bun.randomUUIDv7(),
+          temporalCoverage: null,
+          storageKey,
+          contentHash: new Bun.CryptoHasher('sha256').update(legacyMarkdown).digest('hex'),
+          sizeBytes: Buffer.byteLength(legacyMarkdown),
+          message: 'Historical revision predating the write limit',
+          updatedAt: NOW.toISOString(),
+        })
+      ).state,
+    ).toBe('updated');
     const tooLarge = await context.request({ query: 'from=4&to=5' });
     expect(tooLarge.status).toBe(StatusMap['Unprocessable Content']);
     expect(await tooLarge.json()).toEqual({ error: 'This comparison is too large to display.' });