agent-orchestrator/docs/pro/features/knowledge-base.md

Knowledge Base

This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

The Knowledge Base provides two complementary systems: Persistent Agent Memory (structured knowledge fragments with search and TTL) and the Codebase Symbol Graph (regex-based symbol extraction for code navigation context).

---

Persistent Agent Memory

Purpose

Persistent Agent Memory stores knowledge fragments that agents produce during sessions and makes them available in future sessions. Unlike session anchors (community feature, per-session), memory fragments persist across sessions and are searchable via FTS5.

Memory Fragments

A memory fragment is a discrete piece of knowledge with metadata:

interface MemoryFragment {
  id: number;
  projectId: string;
  content: string;          // The knowledge itself (plain text or markdown)
  source: string;           // Where it came from (session ID, file path, user)
  trustTier: TrustTier;     // agent | human | auto
  tags: string[];           // Categorization tags
  createdAt: string;        // ISO 8601
  updatedAt: string;        // ISO 8601
  expiresAt: string | null; // ISO 8601, null = never expires
  accessCount: number;      // Times retrieved for injection
}

type TrustTier = 'agent' | 'human' | 'auto';

Trust Tiers

Tier	Source	Injection Priority	Editable
human	Created or approved by user	Highest	Yes
agent	Extracted by agent during session	Medium	Yes
auto	Auto-extracted from patterns	Lowest	Yes

When injecting memories into agent prompts, higher-trust memories are prioritized. Within the same tier, more recently accessed memories rank higher.

TTL (Time-To-Live)

Memories can have an optional expiration date. Expired memories are excluded from search results and injection. A background cleanup runs on plugin init, deleting memories expired more than 30 days ago.

Default TTL by trust tier:

Tier	Default TTL
human	None (permanent)
agent	90 days
auto	30 days

Users can override TTL on any individual memory.

Auto-Extraction

When an agent session completes, the dispatcher can trigger auto-extraction. The extractor scans the session transcript for:

• Explicit knowledge statements ("I learned that...", "Note:", "Important:")
• Error resolutions (error message followed by successful fix)
• Configuration discoveries (env vars, file paths, API endpoints)

Extracted fragments are created with trustTier: 'auto' and default TTL. The user can promote them to agent or human tier.

Memory Injection

Before an agent session starts, the top-K most relevant memories are retrieved and formatted into a ## Project Knowledge section in the system prompt. Relevance is determined by FTS5 rank score against the project context (project name, CWD, recent file paths).

Default K = 5. Configurable per project via pro_memory_set_config.

SQLite Schema

In agor_pro.db:

CREATE TABLE pro_memories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT NOT NULL,
    content TEXT NOT NULL,
    source TEXT NOT NULL,
    trust_tier TEXT NOT NULL DEFAULT 'auto',
    tags TEXT NOT NULL DEFAULT '[]',       -- JSON array
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
    expires_at TEXT,
    access_count INTEGER NOT NULL DEFAULT 0
);

CREATE VIRTUAL TABLE pro_memories_fts USING fts5(
    content,
    tags,
    content=pro_memories,
    content_rowid=id
);

CREATE INDEX idx_pro_memories_project ON pro_memories(project_id);
CREATE INDEX idx_pro_memories_expires ON pro_memories(expires_at);

Commands

pro_memory_create

Field	Type	Required	Description
projectId	String	Yes	Project identifier
content	String	Yes	Memory content
source	String	Yes	Origin (session ID, "user", file path)
trustTier	String	No	agent, human, or auto (default: auto)
tags	Vec<String>	No	Categorization tags
ttlDays	u32	No	Days until expiration (null = tier default)

pro_memory_search

FTS5 search across memory fragments for a project.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
query	String	Yes	FTS5 search query
limit	u32	No	Max results (default: 10)

pro_memory_get, pro_memory_update, pro_memory_delete

Standard CRUD by memory ID.

pro_memory_list

List memories for a project with optional filters.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
trustTier	String	No	Filter by tier
tag	String	No	Filter by tag
limit	u32	No	Max results (default: 50)

pro_memory_inject

Returns formatted memory text for system prompt injection.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
contextHints	Vec<String>	No	Additional FTS5 terms for relevance
topK	u32	No	Number of memories to include (default: 5)

pro_memory_set_config

Sets memory injection configuration for a project.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
topK	u32	No	Default injection count
autoExtract	bool	No	Enable auto-extraction on session end

---

Codebase Symbol Graph

Purpose

The Symbol Graph provides structural code awareness by scanning source files with regex patterns to extract function/method/class/struct definitions and build a lightweight call graph. This gives agents contextual knowledge about code structure without requiring a full language server.

Scanning

The scanner processes files matching configurable glob patterns. Default extensions:

Language	Extensions	Patterns Extracted
TypeScript	.ts, .tsx	functions, classes, interfaces, type aliases, exports
Rust	.rs	functions, structs, enums, traits, impls
Python	.py	functions, classes, decorators

Scanning is triggered manually or on project open. Results are stored in agor_pro.db. A full re-scan replaces all symbols for the project.

Symbol Types

interface CodeSymbol {
  id: number;
  projectId: string;
  filePath: string;         // Relative to project root
  name: string;             // Symbol name
  kind: SymbolKind;         // function | class | struct | enum | trait | interface | type
  line: number;             // Line number (1-based)
  signature: string;        // Full signature line
  parentName: string | null; // Enclosing class/struct/impl
}

type SymbolKind = 'function' | 'class' | 'struct' | 'enum' | 'trait' | 'interface' | 'type';

Commands

pro_symbols_scan

Triggers a full scan of the project's source files.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
rootPath	String	Yes	Absolute path to project root
extensions	Vec<String>	No	File extensions to scan (default: ts,rs,py)

pro_symbols_search

Search symbols by name (prefix match).

Field	Type	Required	Description
projectId	String	Yes	Project identifier
query	String	Yes	Symbol name prefix
kind	String	No	Filter by symbol kind
limit	u32	No	Max results (default: 20)

pro_symbols_find_callers

Searches for references to a symbol name across the project's scanned files using text matching.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
symbolName	String	Yes	Symbol to find references to

Returns file paths and line numbers where the symbol name appears (excluding its definition).

pro_symbols_file

Returns all symbols in a specific file.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
filePath	String	Yes	Relative file path

Limitations

• Regex-based extraction is approximate. It does not parse ASTs and may miss symbols in unusual formatting or produce false positives in comments/strings.
• find_callers uses text matching, not semantic analysis. It will find string matches in comments and string literals.
• Large codebases (10,000+ files) may take several seconds to scan. Scanning runs on a background thread and emits a completion event.