Skip to main content

Memory & Knowledge

FleetQ provides two complementary knowledge systems that give agents persistent, searchable context beyond the current conversation window. Both systems are team-scoped and are automatically injected into agent prompts during experiment execution.

Scenario: An agent monitors competitor pricing daily. After each run it stores its findings in Memory. The next day's run retrieves those memories and only reports changes — no duplicate alerts, no context loss between runs.

Memory System

Vector-based semantic search powered by pgvector (1536-dimensional embeddings). Store observations, learnings, and facts. Retrieve by meaning, not exact keywords.

Knowledge Graph

Entity-relationship facts stored in kg_edges. Source → target with typed facts and vector embeddings for semantic search across relationships.

Memory System

The memory system stores arbitrary text as 1536-dimensional vector embeddings using pgvector. Each memory belongs to a team and carries optional metadata (type, source experiment, tags). Retrieval uses cosine similarity so you can ask "what do we know about X?" in natural language.

Store

Save observations, learnings, and context captured during agent runs. Memories persist across experiments and are available to any agent on the team.

Search

Natural language queries are embedded and matched by cosine similarity. Relevant memories surface even when the exact wording differs.

Auto-injection

The InjectMemoryContext pipeline middleware runs before every agent call. It embeds the current task description, searches for the top-k relevant memories, and prepends them to the system prompt automatically — no agent configuration required.

Memory tiers

Every memory entry carries a tier that signals its provenance and reliability. Curated tiers receive a +0.10 cosine similarity boost during retrieval so high-quality knowledge surfaces before raw observations.

Tier Meaning
proposed Raw agent-written observation, not yet reviewed. Default for agent-generated memories.
canonical Curated ground-truth knowledge (+0.10 retrieval boost). Typically promoted by a human or review workflow.
facts Verified factual statements (+0.10 retrieval boost). Suitable for structured data and reference information.
decisions Recorded decisions with rationale (+0.10 retrieval boost). Helps agents avoid re-litigating settled questions.
failures Lessons extracted from failed experiments (+0.10 retrieval boost). Written automatically by the system — see below.

Automatic failure lesson extraction

When an experiment reaches a terminal failure state, FleetQ automatically runs ExtractFailureLessonAction. This action calls claude-haiku-4-5 to summarise what went wrong and stores the result as a failures-tier memory attributed to system:failure_extractor.

On the next run involving the same agent or skill, the lesson is automatically retrieved and injected into the agent's system prompt — the agent learns from past failures without any manual intervention.

Failure lessons are written with proposed_by = 'system:failure_extractor' and tier = 'failures'. They receive the curated retrieval boost and are never overwritten — each failure produces a new, timestamped memory entry.

Knowledge Upload

Upload documents (PDFs, markdown files, plain text) as knowledge sources. FleetQ chunks each document, generates an embedding for every chunk, and stores them as memories tagged with the source document. Retrieved chunks are then available to all agents on the team just like hand-written memories.

Upload via MCP tool 
# From Claude Code or any MCP client connected to FleetQ:
memory_upload_knowledge(
  name: "Q1 2025 Competitor Report",
  content: "...",          # full document text
  source: "manual_upload",
  chunk_size: 512          # tokens per chunk (optional, default 512)
)
Upload product documentation, past research reports, or domain reference material once and all future agents on the team will benefit from it without prompt engineering.

Supported formats for memory_upload_knowledge include PDF, TXT, MD, and CSV. Each source is automatically tagged so you can later filter or delete everything that came from a specific document.

Memory tag scoping

Every memory can carry one or more tags. Retrieval can be scoped to a tag set so that different agents on the same team see completely different memory pools. This is essential when a single team runs multiple customer-facing chatbots (one team, many brands) and you need each bot to stay ignorant of the others' knowledge.

  • RetrieveRelevantMemoriesAction accepts a tags array and filters results before the cosine-similarity ranking.
  • Tags are edited via the Memory Browser UI (per-entry checkboxes) or the memory_update MCP tool.
  • Chatbots declare their allowed tag set in their configuration — the InjectMemoryContext middleware automatically narrows retrieval for every inbound message.

Knowledge Graph data quality

Raw agent-written facts drift fast — the same company can be stored as "Acme", "Acme Corp", "ACME Corp.", or "acme_corp". FleetQ's KG uses two mechanisms to keep the graph clean:

Mechanism What it does
EntityType enum Every entity is classified into one of 11 types (Company, Person, Product, Technology, Concept, Event, Location, Organisation, Document, Metric, Other). Retrieval can scope to a single type for precision queries.
NormalizeKnowledgeInputAction Before kg_add_fact persists a new edge, an LLM pass canonicalises entity names, deduplicates synonyms, rejects garbage strings, and assigns an EntityType. Keeps the graph tight.

Knowledge Graph

The knowledge graph stores structured facts as directed edges between named entities. Each edge has a source entity, a target entity, and a human-readable fact string. Facts are also embedded with pgvector so you can find related facts by meaning, not just by entity name.

Column Description
source_entity The subject of the fact (e.g. "Acme Corp")
target_entity The object of the fact (e.g. "Series B")
fact Human-readable statement (e.g. "raised $20M in Series B in Jan 2025")
fact_embedding 1536-dimensional HNSW vector for semantic search
relation_type Optional label for the relationship (e.g. "funded_by", "acquired")

The InjectKnowledgeGraphContext middleware runs after InjectMemoryContext in the AI pipeline. It embeds the current task and retrieves the top matching facts, injecting them as structured context into the agent prompt.

Knowledge Graph Operations

kg_search — semantic search across all facts

Embed a query and return the most similar facts by cosine distance. Useful for open-ended discovery ("what do we know about Series B rounds?").

bash 
kg_search(query: "recent funding rounds", limit: 10)

kg_entity_facts — get all facts about an entity

Retrieve every fact where the given string appears as either the source or target entity. Useful for building a complete picture of a specific company, person, or concept.

bash 
kg_entity_facts(entity: "Acme Corp")

kg_add_fact — add a new fact

Agents (or humans via the MCP client) can write new facts into the graph during or after a run. The fact is embedded automatically on creation.

bash 
kg_add_fact(
  source_entity: "Acme Corp",
  target_entity: "Widget Pro",
  fact: "launched Widget Pro in March 2025",
  relation_type: "launched"
)
Knowledge graph facts are team-scoped. Every agent on the team shares the same graph, so facts captured by one agent are immediately visible to all others.

Memory Browser

The Memory Browser at /memory lets you inspect, search, and delete memories from the UI. Use it to audit what your agents have learned, remove outdated entries, or verify that uploaded documents were chunked and stored correctly.

Search — enter a natural language query to find semantically similar memories
Browse — paginated list of recent memories with metadata and source tags
Delete — remove individual memories or bulk-clear by filter
Stats — total memory count, storage size, and embedding coverage

MCP Tools

All memory and knowledge graph operations are available as MCP tools so agents and LLM clients (Claude Code, Cursor) can read and write knowledge programmatically.

Tool System Description
memory_search Memory Semantic similarity search over stored memories
memory_list_recent Memory List recently added memories, optionally filtered by type or source
memory_stats Memory Return total count, storage size, and embedding coverage metrics
memory_delete Memory Delete a specific memory by ID
memory_upload_knowledge Memory Chunk, embed, and store a document as knowledge memories
kg_search Knowledge Graph Semantic search across all entity-relationship facts
kg_entity_facts Knowledge Graph Retrieve all facts where the given entity appears as source or target
kg_add_fact Knowledge Graph Add a new source → target fact with optional relation type

API Endpoints

The Memory domain is fully accessible via the REST API under /api/v1/memory. All endpoints require a Sanctum bearer token. See the OpenAPI reference for full request/response schemas.

Method Path Description
GET /api/v1/memory Paginated list of memories (cursor pagination)
GET /api/v1/memory/{id} Get a single memory by ID
POST /api/v1/memory Create a new memory (text is embedded automatically)
DELETE /api/v1/memory/{id} Delete a memory by ID
POST /api/v1/memory/search Semantic search — pass query and optional limit
GET /api/v1/memory/stats Return total count, storage usage, and embedding coverage
Example: semantic search via API 
curl -X POST https://your-fleetq-instance/api/v1/memory/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "competitor pricing changes last quarter", "limit": 5}'
Deleting a memory is permanent. There is no soft-delete for memories. If you need to archive rather than remove, consider tagging memories with a status field in their metadata before deletion.