Knowledge — overview

Knowledge is what the agent knows about a specific business — the store's catalog, its policies, docs and FAQ — turned into a queryable corpus the agent can retrieve from while it works. It's the third pillar of an agent, next to the brain (reasoning, in api) and the hands (the worker).

This page is the conceptual entry: what it's for · what technology we use · how it scales. The engine-level detail lives in LightRAG.

What knowledge is for

The mission is an AI agent for every store (OpenCart first). An agent is only useful to a store if it actually knows that store — every product, price, category, shipping rule and return policy. That knowledge is too large and too store-specific to live in a system prompt, and it changes constantly. So each agent gets its own knowledge base.

Ground the answers. Retrieval-augmented generation: the agent answers from the store's real facts instead of hallucinating. "Do you have this in size M for under €40?" is answered from the catalog, not invented.
The catalog is the killer base. For e-commerce the primary knowledge base is the product catalog — synced from the store (OpenCart API via the agent's connectors), plus policies, manuals and support docs.
Per-tenant, per-agent. Each team/store has its own isolated knowledge; one agent never sees another store's data.

Knowledge ≠ memory

Two different stores, often confused:

	Knowledge	Memory (`agent/memory`)
What it holds	Curated domain corpus — catalog, docs, policies	Episodic / conversational facts about a peer
Size	Large (thousands → millions of chunks)	Small, per-user
Source	Ingested documents	Accrued from conversations
Retrieval	Multi-mode graph-RAG (below)	Lookup / recall
Lives in	Separate LightRAG service, reached over MCP	The agent's own store

Knowledge is the library; memory is the diary. This page is only about the library.

What technology we use

Knowledge = LightRAG (HKUDS), adopted greenfield and run as a separate service, reached by the agent over MCP — knowledge is not baked into the brain, it's pluggable.

LightRAG is a graph-RAG engine: it chunks documents, uses an LLM to extract entities and relationships into a knowledge graph, and serves multi-mode retrieval over it.

Why graph-RAG and not plain vector search:

Plain vector RAG finds the nearest chunks — great for "what's the return window?", weak for questions that span the catalog ("which brands do we stock that ship free?").
The graph captures relationships — product ↔ category ↔ brand ↔ policy — so the agent can answer thematic / global questions, not just nearest-neighbour lookups.

How it's wired into the architecture:

Piece	Role
LightRAG service (Python)	Owns ingestion, the graph, and retrieval. Runs on Hetzner k8s.
`agent/knowledge` slice (NestJS, L5)	A thin gateway: base CRUD, feed documents, proxy retrieval. `ingestion`/`query`/`graph` collapse inside LightRAG, not as our sub-slices.
MCP	How knowledge is reached — the gateway exposes retrieval as `@Tool`s, so it's a pluggable capability *the brain and* the worker call** over MCP, not part of the brain.
Postgres (pgvector + Apache AGE)	One backend for KV + vector + graph. Self-hosted on Hetzner (managed Postgres blocks AGE). Already proven in Ranch.

Retrieval modes (LightRAG): naive (pure vector), local (entity-centric), global (theme/relationship-centric), hybrid (both). The agent picks the mode per question; cheap questions take the cheap path.

And a no-index path — RLM. LightRAG answers from an index built ahead of time; RLM answers from raw data with zero ingestion by recursively inspecting it, paying at query time. Rule of thumb: query-many → index it; query-once or just-uploaded → RLM.

Reached over MCP — by the brain and the worker

All knowledge access is over MCP. agent/knowledge exposes retrieval as MCP @Tools through setup/mcp, and the api hosts the endpoint. agent/knowledge is the only thing that talks to LightRAG directly — every consumer goes through MCP.

Because it's an MCP tool, two clients can query the same base — not just the brain:

Client	When it queries	How
The brain (`orchestrator` in `api`)	during the LLM loop, to ground an answer	calls the MCP tool in-process
The worker (the hands)	mid-task, to pull catalog facts while running a multi-step job	calls the same MCP endpoint with its short-lived session token — no round-trip through the brain

Both hit the same endpoint under the same workspace isolation (derived from the authenticated agent/team), so a worker can never reach another tenant's base. This is the pluggable-over-MCP model: the brain stays small, and any authorized client — brain or worker — plugs into the knowledge capability the same way.

Why a separate service at all: LightRAG is Python, the api is NestJS. Rather than reimplement graph-RAG, we run the library in server mode and keep agent/knowledge a thin proxy. See LightRAG for deployment, the Ranch reference, and the pool design.

How it scales

Scaling knowledge to thousands of stores rests on three ideas.

1. Multi-tenancy via workspaces — natural sharding

1 workspace = 1 knowledge base. LightRAG's workspace parameter gives logical isolation inside shared storage; the service keeps a pool of LightRAG instances keyed by workspace (lazy-init + idle-evict) over one backend.

This is what makes "thousands of stores" tractable: it's not one giant graph, it's many small per-store graphs. Each store's base stays small and fast; the system scales by count of bases, which shards naturally. Security: agent/knowledge derives the workspace from the authenticated team/kb — a client never supplies its own workspace (empty/spoofed workspace = cross-tenant leak).

2. The wall is ingestion, not storage

The expensive part of graph-RAG is indexing: per-chunk LLM extraction of entities and relationships. At millions of files that's a large token cost and a lot of time — inherent to the approach, not a tuning problem. So ingestion is engineered as a pipeline, not a request:

Async / queued via runtime/task (BullMQ) — never inline on the API path.
Incremental — re-index only what changed (catalog deltas), not the whole base.
Rate-limited and token-budgeted — bounded LLM spend per base.
Cheap path available — offer naive vector-RAG and use the graph only where it earns its cost.

3. Backend by scale shape

The storage backend follows the shape of the load, not a single default:

Scale shape	Backend
Many small bases (the e-commerce case — thousands of stores)	Unified Postgres (pgvector + AGE) — app data + KV + vector + graph in one DB
*Millions of chunks in a single* base**	pgvector strains (~a few M) and AGE is unproven at that size → Neo4j + a dedicated vector DB (Qdrant / Milvus)

WARNING

LightRAG is young (2024). Benchmark at the target scale before committing a backend, and pin the version — its storage schema changes between releases.

Knowledge — overview ​

What knowledge is for ​

Knowledge ≠ memory ​

What technology we use ​

Reached over MCP — by the brain and the worker ​

How it scales ​

1. Multi-tenancy via workspaces — natural sharding ​

2. The wall is ingestion, not storage ​

3. Backend by scale shape ​

See also ​