Agent Memory (Knowledge Base)

15. Agent Memory (Knowledge Base)

When Agent Memory is enabled, the AI can generate reusable business knowledge suggestions from conversations (terminology, business rules, analysis preferences, domain context, etc.). New suggestions first enter the current workspace's Queued Knowledge queue; only after you approve and merge them into User or Project knowledge do they inject into the model in later conversations. You do not need to repeat the same background in every new conversation—but if you turn off the memory master switch, nothing is extracted in the background or injected; if you only turn off Automatic suggestions, background extraction after a conversation stops while approved knowledge is still injected, and the Agent can still call propose_knowledge.

15.1 How Knowledge Suggestions Are Created

When Enabled (master switch) is on, Automatic suggestions is on, and a usable LLM is configured (API Key, etc.), after each AI conversation ends normally the system runs in the background, non-blocking:

Extract: The LLM identifies reusable knowledge fragments only from the user messages in the latest conversation turn (default the last 8 messages); one-click System instruction triggers (HTML Report, Resolve Comments, Execute Plan, etc.) do not participate in extraction. Each suggestion must carry an evidence_quote (a quote of your own words), which the backend verifies must appear in those user messages, or it is dropped. Suggestions include a Type: rule (constraints, preferences, process) or info (definitions, background, facts). With a focused project, the system prefers the project level and pre-fills the project ID (from the current conversation context, falling back to the session when necessary).
Dedupe: Compare against approved knowledge, pending items in the queue, and (at the project level) the same project's knowledge file; skip semantic duplicates; an updated phrasing may carry supersedes to replace an old pending item.
Enqueue: Items that pass validation and dedupe are written to the current workspace's Queued Knowledge (a JSON queue; not written to the formal User / Project Markdown knowledge files until approved). Passive extraction enqueues at most 3 items per conversation turn.
Agent proactive proposals: During analysis the Agent can call propose_knowledge to send cross-conversation reusable rules, such as definition or field pitfalls, into the same queue (tagged Agent proposed). These also require Apply before injection; they do not change Agent behavior before approval. They need a verifiable evidence_quote (from recent user or tool output, or a write-type tool argument such as the body of an add_report report); they must not propose SQL or query-execution-state content. Pitfalls for a single query step belong in the Query Step Ledger ([[QUERY_STEP]]), not the knowledge base. Rate limits: per user message (the full Agent reply stream), at most 2 successful enqueues and 3 tool calls (including failures); at most 5 pending agent proposals per conversation (Apply or Dismiss frees the quota). An enqueue failure (for example failed evidence validation) is folded in chat like any other tool and does not show an approval card; only a successful enqueue shows an Agent proposed knowledge approval card. Proactive proposals are controlled only by Enabled and are not affected by Automatic suggestions.

If Enabled is off or the LLM is not configured, neither passive extraction nor Agent proposal enqueue runs. If only Automatic suggestions is off (Enabled still on), background extraction after a conversation does not run, but approved knowledge is still injected and the Agent can still enqueue proposals. The legacy use_knowledge_extraction_queue is synced with Enabled automatically when settings load; it is not a separate user switch.

15.2 How Knowledge Is Used (Agent Injection)

Only content merged into the knowledge files (the global User Knowledge and each project's Project Knowledge) is injected into the system prompt when the AI replies. Approved knowledge files use the two sections ## Rules / ## Info (a legacy four-section layout or ## Notes migrates automatically on read); currently the full Rules and Info are injected together (not Rules only).
Pending items in Queued Knowledge do not enter the model context.
When Enabled is off: no background extraction, no injection, no controlled writes or Agent proposals—the Agent behaves as if there were no knowledge base.
When only Automatic suggestions is off: no background extraction; approved knowledge is still injected, and manual editing and queue Apply / Dismiss still work.

15.3 Opening the Dialog and the Enabled Switch

Click the lightbulb icon (Lightbulb) in the top-right of the title bar to open the Agent Memory management dialog.

When memory is on and the current workspace's queue has pending items, a red dot appears on the bulb (no dot when memory is off).
Below the dialog title is an Enabled toggle: when off, the main content area is covered by a translucent overlay with an English explanation (essentially: memory is off, nothing is injected, and background extraction and Agent proposals are paused; you must turn it back on to continue editing and using it). You must switch it back on to edit and process the queue.
Below that is an Automatic suggestions toggle (changeable only when Enabled is on): turning it off stops background extraction after conversations; it does not delete or disable approved knowledge. When Enabled is off this toggle is disabled but still shows your previous preference, and it is restored after you turn Enabled back on.

At the top of the dialog are two tabs: Agent Memory (edit the knowledge base) and Queued Knowledge (n) (n is the current pending count).

15.3.1 First Launch: Agent Preferences

The first time you finish setting up the LLM connection (API Key, etc.) and no User Knowledge file exists on disk, the Agent Preferences dialog opens automatically (after the welcome video closes or a hot-update skips the video). The flow is: Onboarding video (skippable) → set API Key → Agent Preferences (Skip allowed) → first chat.

Four settings (English UI):

Item	Description
Reply language	Reply language: follow your messages, English, Traditional Chinese, Simplified Chinese, Japanese
Response style	Level of detail: Concise / Balanced / Detailed
Emoji in replies	Whether to allow emoji: Allow / Avoid
Clarifying questions	How proactively to ask: Minimal / Balanced / Ask proactively

Save preferences: Writes the options to ## Rules in user_knowledge.md (one English rule each, for Agent injection).
Skip for now, or pressing X / Esc: Still creates an empty User Knowledge template file (Rules is (none yet)); you can edit it later in Agent Memory via the lightbulb icon.
Clicking the backdrop outside the dialog does not close it; you must explicitly Save / Skip / X / Esc.
If the Agent Memory master switch is off, you can still save preferences to the knowledge file first; injection begins on the next turn after you turn Enabled on.
It auto-opens only once, when no User Knowledge file exists yet; edit it manually in Agent Memory afterward.

Project knowledge files: From this version on, creating a new project automatically creates that project's project_knowledge.md template (## Rules / ## Info). Older projects that existed before the upgrade are not backfilled automatically; the file is still created on demand on the first write or Reorganize.

15.4 Agent Memory Tab (Editor and Library status)

The Agent Memory tab has a three-column layout:

Left (document list): User Knowledge (Global) is pinned at the top; below it is the list of each project's Project Knowledge. The currently focused project shows a green Eye icon on the right of its row.
Center: A Markdown editor to view and edit the currently selected knowledge file.
Right (Library status): Shows statistics and actions (see the table below).

Field	Description
Rules	The number of leaf entries under `## Rules` in the open knowledge file (actual rule statements; parent rows that serve only as group headers are not counted)
Info	Same, the number of leaf entries under `## Info`
Characters	The file's character count / injection cap (User 6,000, Project 20,000; matches the Agent injection budget, not the editor Save cap)
Last updated	The last time the file was written to disk (updated after Save, Apply, Reorganize)

Below Last updated, depending on the open file (User / Project), a Reorganize character threshold note is shown: below 2,500 characters (User) or 5,000 characters (Project), reorganize outputs top-level bullets only; at the threshold it allows "a short catalog heading + indented sub-bullets" (the parent row is a lookup tag, with facts written in the children). If a file is below the threshold but already contains indented sub-bullets, it warns that Reorganize will flatten them. When edits are not yet saved, statistics are based on disk with a Counts update after Save hint. This threshold differs from the Characters injection cap (6,000 / 20,000).

The pending count is shown only on the top Queued Knowledge (n) tab title. Below are Save and Reorganize (see §15.6).

15.5 Queued Knowledge Tab

After a successful Agent proposed enqueue, a knowledge proposal card appears in the AI chat on the right (showing the suggested content, evidence, and an optional rationale), where you can directly approve User / Project / Dismiss—this does not pause the Agent the way ask_user does; the conversation can continue. You can also handle the same item later in the Queued Knowledge tab.

Card state persists: After you apply or skip, the card shows Applied / Dismissed; after restarting the app or reopening the conversation it still syncs the queue state and does not show clickable buttons again.
Project default target: With a focused project, the card's Project defaults to applying to that project (not the first project in the list).
Where to look after applying: User writes to the global User Knowledge; Project writes to that project's Project Knowledge (you must select the matching project on the left in Agent Memory). On success an English toast shows the write location.
Queued list behavior: The Queued Knowledge tab shows only pending items; after a successful apply the item disappears from the list—this is expected and does not mean the knowledge was lost.
Do not apply twice: An item already Dismissed or applied is not rewritten when clicked again; the system shows Already dismissed or Already saved—check the corresponding User / Project knowledge file.
Sync with Agent Memory: After applying on a card or in the Queued tab, if the Agent Memory window is already open, the queue and editor refresh automatically; a Project apply switches to the target project.

In Queued Knowledge you review each suggestion's text and suggested level (user / project) item by item. The list tags the source: Chat extraction (passive extraction after a conversation ends) or Agent proposed (a proactive proposal by the Agent during analysis). When you select an item, the right side shows:

Source: Chat extraction / Agent proposed.
Agent rationale (if any): a short note from the Agent for review, not injected into the model.
Evidence: the verifiable quote it is based on (your own words or a tool output snippet; pre-upgrade data may show No evidence (pre-migration item)).
Knowledge: a summary of the content suggested for merging into the knowledge base.
Type: rule or info.
Suggested project: the suggested project ID; in focused-project conversations most are pre-filled automatically; if it is still invalid or missing, the list flags it with an amber Pick project.

For a selected item you can:

User: Apply the suggestion to the global User Knowledge (merge into the matching section).
Project: Apply it to project knowledge. If the item is flagged Pick project or has no valid project specified, the system opens a Pick project dialog for you to choose the target project before applying.
Dismiss: Skip the item without writing it to a knowledge file.

There is also Process all (by LLM recommend) and other batch processing; items that need a manual project choice (Pick project) are skipped and must be applied individually. The interface may show shortcuts: 1 User / 2 Project / 3 Dismiss (and ↑ / ↓ to move between rows).

15.6 Save, Reorganize, and Content Validation

Button Description

Save Saves the manual edits in the editor. The system validates the content (for example an 8,000-character length cap). If a legacy PENDING section is still present, saving automatically merges it into ## Info and removes that section. Missing standard headings may show a warning but still save; a later Reorganize will try to repair the structure

Reorganize Manually triggers an LLM reorganize: it tidies the User or Project knowledge file currently selected on the left (Rules / Info): dedupe and condense wordiness. By file character count: User below 2,500 or Project below 5,000 characters allows top-level bullets only; at the threshold it can consolidate into "a short catalog heading (lookup key) + indented sub-bullets." Items newly Applyed from the queue are first written as single top-level bullets and tidied by the next Reorganize. It backs up a .bak before reorganizing; it does not overwrite when the structure is invalid (such as ###, orphan indentation, or a small file that contains indented sub-bullets). When the editor has unsaved changes you must Save first (the button is disabled). While in progress the editor shows a translucent overlay with English status (including an estimated number of seconds); up to about 300 seconds (5 minutes); you can switch to another knowledge file and Reorganize in parallel; closing the management window does not cancel the background request

Button	Description
Save	Saves the manual edits in the editor. The system validates the content (for example an 8,000-character length cap). If a legacy `PENDING` section is still present, saving automatically merges it into ## Info and removes that section. Missing standard headings may show a warning but still save; a later Reorganize will try to repair the structure
Reorganize	Manually triggers an LLM reorganize: it tidies the User or Project knowledge file currently selected on the left (Rules / Info): dedupe and condense wordiness. By file character count: User below 2,500 or Project below 5,000 characters allows top-level bullets only; at the threshold it can consolidate into "a short catalog heading (lookup key) + indented sub-bullets." Items newly Applyed from the queue are first written as single top-level bullets and tidied by the next Reorganize. It backs up a `.bak` before reorganizing; it does not overwrite when the structure is invalid (such as `###`, orphan indentation, or a small file that contains indented sub-bullets). When the editor has unsaved changes you must Save first (the button is disabled). While in progress the editor shows a translucent overlay with English status (including an estimated number of seconds); up to about 300 seconds (5 minutes); you can switch to another knowledge file and Reorganize in parallel; closing the management window does not cancel the background request

15.7 Notes

User Knowledge is a single Markdown file (such as user_knowledge.md); Project Knowledge is a file inside each project directory. Both can be edited manually right in the Agent Memory tab.
Knowledge extraction requires a valid LLM configuration and Enabled on; otherwise extraction is skipped and other features are unaffected.
Queue items do not appear in the model context before they are applied.
Knowledge suggestions must be traceable to your own words (evidence_quote); a suggestion that cannot be matched to a user message is not enqueued, which avoids the AI fabricating business rules.
Both User and Project knowledge can be Reorganized manually in the Agent Memory tab (whichever file is open is the one tidied).
Before Reorganize a .bak is backed up, so you can reference the disk copy if you are not satisfied with the result.
Knowledge keeps your original language.
Injection matches the Mode (see Mode in Library status): in flat mode (User below 2,500, Project below 5,000 characters) the full text is injected; in catalog mode (at the threshold) a catalog index is injected by default, and the Agent can call expand_knowledge_catalog to load the full entries.
When at catalog character size but not yet organized into a catalog (all top-level, no parent+child structure), before the first message to the Agent in a new conversation, the system may run a Reorganize once automatically (the interface shows "Reorganizing Agent Memory before injection…"); it is not repeated within the same conversation. If it failed before, a new conversation can try again. When the Agent Memory editor is open with unsaved changes, Save first so the automatic Reorganize does not overwrite the older content on disk (the same risk as a manual Reorganize).

Design note: For the full Agent Memory governance flow, see Governed Agent Memory.