docs: chunk-level search PRDs + entity-spec consolidation + PDF-agent tutorial - #249
Merged
Conversation
Update prd-knowledge.md to match the DocumentChunk model from issue #244 / PR #245: document search now runs against DocumentChunk.embedding (not Document), results carry chunk_id + page, and mapRawDocument's disk-read path is replaced by mapChunkResult. Updates the status table, Phase 1 note, response example, implementation architecture, and data model. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ErUBchseZrpYysrq5rZMNF
Deploy Outputs
|
…c + knowledge_config
Make prd-knowledge.md authoritative for the knowledge_config shape and the
entity-based query surface; reduce prd-memories.md's duplicated copies to
links so the two PRDs stop drifting.
knowledge PRD:
- Add canonical KnowledgeConfig schema (all read-scope + write-side fields)
under Knowledge Config, marked as the single source of truth.
memories PRD (consolidation):
- Knowledge Config / Three Retrieval Paths / Merge Behavior → link to
knowledge PRD; keep only memory-owned fields (write_memory_id, extraction).
- Phase 5c entity-query params → link to knowledge PRD Phase 3.
- Stale KnowledgeConfig TS interface → link to canonical schema.
memories PRD (verified factual fixes):
- VECTOR(1536) → VECTOR(EMBEDDING_DIMENSIONS) on MemoryEntry + MemoryEntity
(matches the models; embeddings are env-dimensioned, not 1536).
- write_memory tool takes { content } only (target bound from write_memory_id),
correcting the { content, memoryId } example.
- Add memories:ListEntityEntries permission for GET /entities/:id/entries.
- Fix malformed Phase 5 heading nesting (5a/5b/dedup/5c now sub-sections).
- Note stale MemoryEntryEntity links must be cleared on entry update.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErUBchseZrpYysrq5rZMNF
arantespp
changed the title
End-to-end tutorial validating the PDF-agent build plan: upload PDFs → ingest into chunked/embedded Documents under a path prefix → scope an agent with knowledge_config → retrieve automatically and via search-knowledge → cite document_id + page. - Two real, tiny single-page PDFs embedded as base64 (validated with unpdf, the server's parser) with short facts so a small local model (qwen2.5:0.5b) answers reliably from injected context. - Covers page vs size chunk strategies, chunk-level citations, and both retrieval modes. CLI / SDK / curl tabs. - Gated in .tutorialsignore until #245 (POST /documents/ingest) is merged; remove that line once the server supports ingestion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ErUBchseZrpYysrq5rZMNF
arantespp
changed the title
Remove agent-with-pdfs from .tutorialsignore. POST /documents/ingest and the DocumentChunk model are now on main, so the tutorial runs end-to-end in CI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ErUBchseZrpYysrq5rZMNF
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only PR with three related pieces of work around the Knowledge/Documents/Memory feature area.
1. Chunk-level document search (issue #244 / PR #245)
prd-knowledge.mdpreviously described document search as document-level viamapRawDocument()reading file content from disk — that path no longer exists.mapChunkResult()+DocumentChunk → Document → File → Projectjoin), and Data Model now reflect chunk-level search (DocumentChunk.embedding,chunk_id+page).2. Single source of truth for
knowledge_config+ entity-query specThe two PRDs duplicated "Knowledge Config", "Three Retrieval Paths", "Merge Behavior", and the entity-query parameters — and had drifted (
actor_idvsactor_ids,entity_types/relationship/directionpresent in one but not the other).KnowledgeConfigschema and remains owner of the entity-query surface (Phase 3).write_memory_id,extraction) and the memory-side data layer (resolveEntitySearch()).Plus verified factual fixes:
VECTOR(1536)→VECTOR(EMBEDDING_DIMENSIONS);write_memorytakes{ content }only; addedmemories:ListEntityEntriespermission; fixed Phase 5 heading nesting; noted stale-link cleanup on entry update.3. New tutorial — "Agent over a Library of PDFs"
packages/website/docs/tutorials/agent-with-pdfs.mdvalidates the PDF-agent build plan end-to-end:/manuals/(page vs size chunking).knowledge_configprefix.search-knowledgequery.document_id+page.Two real single-page PDFs are embedded as base64 — validated with
unpdf(the server's own parser) — with short facts so a small local model (qwen2.5:0.5b) answers reliably from injected context. CLI / SDK / curl tabs.Not included (need a decision, raised in review)
MemoryEntry.embeddingisNOT NULL(hard-fail) whileDocumentChunk.embeddingis nullable/non-fatal.[Memory: <id>]in code vs[Memory: <name>]in the PRDs — a code bug, out of scope for a docs PR.🤖 Generated with Claude Code
https://claude.ai/code/session_01ErUBchseZrpYysrq5rZMNF