Memory & Knowledge

Task state, user preferences, and external source material can all influence an answer, but they should not share one storage and loading policy. aibuddy keeps them in task, user, and document scopes and applies a different selection path before each enters the model working set.

Three information classes use different scopes

Information systemAppropriate contentLifecyclePath into active work
Task contextCurrent goal, plan, tool results, and execution stateOne taskAssembled by the runtime and compacted at thresholds
User memoryStable preferences, behavioral feedback, and non-recoverable project backgroundOne user across tasksSelect from a lightweight index, then read matched bodies
Knowledge baseSource material whose provenance and section structure must remain intactPersonal or system scopePublish, attach to a task, then read through a knowledge subagent

For example, “use a concise format for this report” belongs to the current task; “use a concise format for every weekly report” can become user memory; and a company policy remains a reviewable, citable knowledge document. Scope separation prevents transient state from becoming a lasting preference and avoids replacing formal sources with uncited memory.

Memory is a maintainable user record

Each memory is an independent Markdown record. Frontmatter stores its name, description, type, provenance, and recall telemetry; the body stores the complete content. Types express intended use rather than merely copying the conversation topic:

Guarded writes and selective recall for user memory Automatic extraction and explicit memory tools use different write paths into per-user memory records. Recall scans a lightweight manifest before selecting and reading at most five bodies. User memory: guarded writes, on-demand recall The automatic path discovers durable facts; the manual path retains higher content priority. Background extraction A non-blocking auxiliary path after an ordinary task Deterministic cue gate preference · identity · correction no signal, no model call Latest three pairs about user · durable next week not recoverable elsewhere Pre-write reconcile salience · equivalence same-type near-duplicate merge Explicit memory tools save · recall · update · delete Provenance is always manual Explicit writes exclude auto extraction Per-user Markdown memory records System-set provenance · manual content protected · continuous recall telemetry Selective recall Scan light manifest up to 200 recent records Light model selection choose clearly relevant records Validate and read bodies at most 5 per recall Enter active task context no body injected without a match Selection, extraction, or write failures skip the auxiliary path without changing the task result

TypeStored content
userRole, expertise, background, and stable preferences
feedbackCorrections or confirmations about agent behavior
projectDurable project context that cannot be recovered from project files or connected systems
referencePointers to external systems, pages, or source material

Explicit memory-tool writes receive manual provenance, while background extraction receives auto; the system sets provenance and the model cannot declare it. Create and update are distinct operations. An update preserves the original provenance, recallCount, and lastRecalledAt, preventing an accidental same-name write from breaking record continuity.

The agent can save, recall, update, or delete an individual memory. Clearing the complete memory set remains a user-side management capability and is not exposed as an agent memory tool, preventing one model call from removing the user’s entire collection.

Memory is isolated per user and persists outside task sandboxes. The storage layer needs only narrow list, read, write, and delete operations, allowing a filesystem, object store, or database to retain the same maintenance and recall semantics.

Recall selects an index before reading bodies

The runtime does not add every memory to every model request. Recall currently has three stages:

  1. Scan memory frontmatter into a manifest containing only type, filename, modification date, and a short description.
  2. Ask a separate lightweight model to select records clearly relevant to the current request.
  3. Validate the filenames and load only the selected bodies, currently up to 5 per recall.

This path separates relevance judgment from full-content loading. The selector can reason semantically, while long-lived records consume main-task context only after a match. If model selection is unavailable, the memory tool can fall back to lexical matching across descriptions and bodies. Selection or read failure yields an empty result instead of stopping the main task.

The current index window scans at most 200 memories and orders them by modification time. Successful recall updates recallCount, lastRecalledAt, and file activity, helping records still in use remain in the active window. When a memory result participates in later reasoning, it is compacted to count and status; the client can still display the surfaced content without making later steps repeatedly carry every body.

Automatic extraction is a constrained write path

Background extraction does not turn every conversation into memory. At task completion, the system inspects only the latest 3 user-assistant pairs and first applies deterministic cues for potentially durable information. Without a preference, identity, feedback, or persistent-project signal, no model extraction starts. The process also skips a window whose latest assistant turn already invoked explicit save, update, or delete memory operations.

A candidate must be user- or durable-project-specific, likely to remain valid, and unavailable from files or connected systems. The write path then reconciles it against existing records:

  1. Discard low-salience candidates.
  2. Treat equivalent content as a no-op.
  3. Reuse an existing record when same-type description similarity reaches the current 0.6 threshold.
  4. Prevent automatic extraction from overwriting a manual memory.
  5. Preserve filename, provenance, and recall telemetry on updates.

Automatic extraction is therefore a “cue gate—model judgment—similarity merge—provenance protection” process, not a transcript archive. Failure at any stage is logged and skipped without affecting task completion.

Knowledge must be published before entering a task

Knowledge import preserves Markdown structure and derives heading levels, stable section anchors, line ranges, and approximate sizes. A short summary establishes a lightweight document map. Summary generation is non-blocking: failure does not discard the body or prevent review.

Knowledge review, publication, and progressive disclosure Knowledge ingestion derives a body, outline, and summary before the pending-to-ready review boundary. User visibility and task attachment then filter the set. A knowledge subagent expands from document map to outline and bounded sections. Knowledge: establish a trusted set, then expand its body Publication controls whether a document is searchable; task scope controls what is searchable now. Document ingestion and publication Import Markdown preserve authored structure Derive outline and summary sync outline · non-blocking summary pending review body and structure ready enter searchable documents Reingestion returns to pending, rebuilds the outline, and clears the stale summary; late summaries do not overwrite review Runtime visibility is the intersection of three conditions status = ready ∩ visible to current user ∩ attached to current task = visible document set Knowledge subagent reads progressively in isolated context Document map title · summary · section count read_doc · search_docs outline or section-level hits read_section bounded page and cursor Return synthesized answer document and section citations · gaps The corpus can grow while one task expands only the body relevant to its question.

New and reingested documents enter pending; only ready documents are available to agent retrieval. Administrators review system-scoped documents, while owners manage personal documents. Editing a body reparses its outline and invalidates the previous summary. Incomplete or unconfirmed material therefore cannot enter an answer directly.

A retrieval must satisfy three conditions together:

  • The document is ready.
  • The current user can see the system or personal document.
  • The document belongs to the knowledge set selected for the current task.

Task knowledge selection is an editable resource. A change applies from the next message, while already-produced history remains unchanged.

Knowledge bodies unfold from map to outline to section

aibuddy neither loads every knowledge body at task start nor exposes all low-level knowledge tools directly to the main agent. A built-in knowledge subagent appears only when the capability is available and the task has attached documents. It performs navigation in an isolated context.

StageInternal mechanismInformation exposedDecision supported
Document mapTask initializationTitle, scope, summary, and section countSelect documents to inspect
Document locationread_doc / search_docsOutline or search hits with section anchorsIdentify relevant sections
Evidence readingread_sectionOne bounded section page, child sections, and a continuation cursorRead the body required for the answer

search_docs ranks section-level results across English terms, Chinese characters and bigrams, and quoted exact phrases. It returns one representative hit per section so repeated matching lines do not flood the result. read_section addresses content through stable anchors and pages long sections with a cursor.

Progressive disclosure decouples corpus growth from per-request context cost: the collection can grow while the model expands only material relevant to the current question. The knowledge subagent returns a synthesized answer with document titles and section citations. If the attached corpus does not cover the question, it reports the gap instead of filling it with general knowledge. After retrieval, intermediate bodies can be compacted while document and section pointers remain for traceability.

Design boundaries

  • User memory stores stable, user-specific information. It is not an uncited fact store and should not duplicate information recoverable from project files.
  • Knowledge stores structured, reviewable source material. It does not implicitly capture user preferences or current task progress.
  • Knowledge search uses document structure and ranked terms rather than vector chunks. It prioritizes well-structured internal documents and does not claim to cover every semantic retrieval scenario.
  • Knowledge import currently accepts standard Markdown and UTF-8 text. PDF, DOCX, OCR, and other formats require conversion first.
  • Memory selection, automatic extraction, and summary generation are auxiliary model paths. Failure falls back to an empty result, lexical recall, or a skipped update without blocking the main task.

Implementation anchors

Design responsibilityModule
Memory records, provenance protection, and recall telemetryMemoryService
Semantic selection over the manifestmemory-recall
Automatic extraction, deduplication, and conflict handlingmemory-extraction
Knowledge publication, visibility, and section retrievalKnowledgeService
Isolated progressive knowledge readingknowledge-subagent

These modules compose through narrow interfaces. Changing the persistence implementation or lightweight model does not alter the scope boundary between task context, user memory, and knowledge documents.

Was this page helpful?
Edit on GitHub