Governable Agent Memory: Layering, Approval, and Catalog Injection

Methodology answer B: knowledge is not better the more automatic it is, but better the more visible, reviewable, and disableable it is. For step-by-step instructions, see User Guide §15.

Series Position

For the complete guide, see Series Guide and Product Positioning.

1. Problem Definition: Why Automatic Memory and Approval-Free RAG Are Insufficient

Many AI products treat "remembering what the user said" as a default capability: when the conversation ends, it is written to a vector store, and next time similar fragments are retrieved and stuffed back into the prompt. For data analysis scenarios, this brings three kinds of risk—not because the model is not smart enough, but because the memory lacks governance:

1. Invisible: the user does not know which rules the model "thinks" hold.
2. Uncontrollable: an erroneous inference or hallucination may be treated as a long-term fact.
3. Not disableable: compliance or sensitive projects need to explicitly cut off memory injection.

Lantide Data's position is: only content approved by the user and written to the formal knowledge file enters the Agent context; the rest of the suggestions stay in the queue until Apply or Dismiss.

Some products achieve in-session adaptive memory by "understanding the schema/business rules better the more you ask"—convenient, but once a cross-project definition is written wrong, the cost is higher than "remembering a little less." Lantide chooses Queued Knowledge + manual Apply: a definition must be verifiable via evidence_quote and is injected only after approval, complementary to Workflow §3 SQL-first—what the knowledge file precipitates is the already-reviewed definitions, not a byproduct of the Insights endpoint.

2. Layering · Typing · Approval

2.1 Two Layers of Knowledge

Project knowledge is injected only when the project is focused and Agent Memory is Enabled.

2.2 Rules and Info

Each knowledge file has two fixed sections (the old four-section version is migrated on read):

## Rules    ← constraints, processes, analysis/presentation preferences (how to do it)
## Info     ← definitions, background, column semantics (what it is)

When extracted into the queue, an item is tagged with a Type: rule or info, and after approval is written to the corresponding section.

2.3 The Master Switch Enabled and Automatic suggestions

• After Enabled (the master switch) is turned off: no background extraction, no injection, no queue red dot; Agent proposals and governed writes are paused together. The Agent behaves as if there were no knowledge base.
• When Automatic suggestions is turned off (Enabled still on): the background extraction LLM / enqueue after a conversation ends does not run; already-approved knowledge is still injected, manual editing and queue approval are still available, and the Agent's propose_knowledge can still enqueue.

For details, see §15.3.

3. The Two-Stage Knowledge Flow

flowchart LR
  chat[Conversation ends]
  extract[LLM extracts suggestions]
  queue[Queued Knowledge]
  apply[Apply User / Project]
  file[Rules + Info knowledge file]
  inject[Inject into next round's prompt]
  chat --> extract --> queue
  queue -->|Apply| apply --> file --> inject
  queue -->|Dismiss| dismissed[Record hash, no longer suggest]

Principle: a queue item never goes directly into the model; only after being written to the on-disk knowledge file is it injected.

4. Queued Knowledge: The Review Entry

4.1 Extraction Rules

When both Enabled and Automatic suggestions are on and the LLM is available, the background runs after a conversation ends normally:

• It scans only the user messages in the most recent round (the most recent 8 by default).
• System instructions (Execute Plan, Resolve Comments, HTML Report instructions, etc.) do not participate in extraction.
• Each suggestion must include an evidence_quote (a quote of the user's original words); the backend verifies that the quote appears in the above user messages, otherwise it is discarded.
• At most 3 items are enqueued per round.
• When a project is focused, suggestions lean toward the project layer and pre-fill the project ID.

When only Automatic suggestions is turned off, the above background flow is skipped; it does not affect injection of already-approved knowledge.

4.2 Deduplication and Supersession

A semantic comparison is made against approved knowledge, the pending queue, and the same-project knowledge file; duplicates are skipped. If it is an updated formulation, it can supersede an old pending item with the same semantics. After Dismiss, the hash is recorded to avoid repeatedly suggesting the same item.

4.3 The Agent's Proactive Proposal (propose_knowledge)

During analysis, the Agent can call propose_knowledge to send a reusable definition/column rule into the same Queued Knowledge queue. Same as passive extraction: not injected before approval.

Division of labor with the Query Step Ledger:

A proposal must attach a verifiable evidence_quote; writing execution-state content such as SQL or cache table names into the knowledge file is prohibited; for rate-control and validation details, see AI Agent Architecture §8.

4.4 Approval Operations

Agent proposed and Chat extraction share the same queue. After enqueuing, approval can happen in two places:

• The knowledge proposal card in the conversation stream — User / Project / Dismiss (does not pause ReAct, unlike ask_user); the card is persisted according to queue state and stays in sync after reloading the conversation; when a project is focused, Project writes to that project by default.
• The Queued Knowledge tab — Apply to User, Apply to Project (a Pick project item requires manually selecting a project), or Dismiss; batch Process all skips items that still require manually selecting a project.

The list shows only pending items and distinguishes their source; removal from the list after applying is expected. The chat card and Agent Memory refresh bidirectionally via queue-change events; on successful apply, a toast indicates the User or Project destination.

For the operation interface, see §15.5.

5. The Knowledge File Contract

5.1 Entry Structure

• Primarily Markdown top-level bullets; there can be one level of indented sub-entries (catalog mode).
• Leaf entries: the actual rule/fact body; a parent line that serves only as a grouping heading does not count toward the Rules/Info count in Library status.
• Save has an upper limit of 8,000 characters (different from the injection budgets of 6,000 / 20,000).

5.2 Library status

The right side of the editor shows the number of Rules/Info leaf entries, character count / injection limit, Last updated, and Mode (flat / catalog). Statistics are based on the content saved to disk; when unsaved, it prompts Counts update after Save.

6. Apply and Reorganize

6.1 Apply

After approval, it is merged into the corresponding ## Rules or ## Info, with a new entry usually written as a single-line top-level bullet, to be tidied at the next Reorganize. The User and Project destinations differ, so do not look in the wrong tab. Re-applying a queue item that has already been Dismissed or processed will not write to the file again (repeated operations are safe); the frontend prompts Already dismissed / Already saved rather than a fake success.

6.2 Manual Reorganize

Triggers the LLM on the currently left-selected User or Project file: deduplicate, condense redundant wording, and decide by word count whether to collapse into "short catalog headings + indented sub-entries."

• A .bak backup is made before reorganizing; an invalid structure is not overwritten.
• When unsaved, the Reorganize button is disabled.
• While in progress: the editing area is masked with status text, for up to about 300 seconds; you can switch to another knowledge file and reorganize in parallel; closing the dialog does not cancel the background request.

For details, see §15.6.

6.3 Pre-inject Reorganize

When the catalog word count has been reached but the file is still entirely top-level (no parent+child structure), the system may automatically Reorganize once before the first message of a new conversation is sent to the Agent (the interface prompts "Reorganizing Agent Memory before injection…"). Within the same conversation, each file is tried at most once; failure does not block the chat, and a newly opened conversation can try again. If the editor has unsaved changes, Save first to avoid the auto-reorganize overwriting the disk.

7. flat → catalog → expand

When the knowledge file is short, the model sees all Rules/Info at once; after exceeding the word-count threshold, injection becomes a "list of catalog labels," and the model needs to use expand_knowledge_catalog to expand on demand—similar to "give the index first, then look up the details"—to avoid long-term knowledge blowing up the context.

7.1 Injection Modes

When the injection budget is exceeded (User 6,000, Project 20,000 characters), a truncation notice is appended.

7.2 expand_knowledge_catalog

In catalog mode, the system prompt reminds the Agent to call expand_knowledge_catalog with the exact parent label to batch-load the complete entries (including indented sub-entries). For the tool implementation and state restrictions, see AI Agent Architecture §8.

7.3 project_id Semantics

• The project_id used during injection is based on the session's focused project.
• During extraction into the queue, the focused project from the conversation context is used first, then a fallback to the session, to reduce Pick project.

8. Relationship with Answer A (Agent-Era Data Analysis Workflow)

The two are orthogonal: a good delivery process does not equal automatic memory; nor should memory replace the explicit hypotheses on a Plan.

9. Anti-patterns

10. Closing

Agent Memory in Lantide Data is a governance system, not a byproduct of the chat log: visible, reviewable, disableable, with definitions entering the model only after evidence and Apply.

This complements the workflow's SQL-first—the Plan carries the hypotheses of a single analysis, while the knowledge file carries cross-project definitions. The next article, Prompt and Context Engineering, explains how approved knowledge is assembled into the model together with the Context Summary and the State Prompt.