The Contents Database (Contents DB) is an optional component that enhances Knowledge with content tracking and management features. It acts as a control layer that maintains detailed records of all content added to your Knowledge.

​
What is Contents DB?

Contents DB is a table in your database that keeps track of what content you’ve added to your Knowledge base. While your vector database stores the actual content for search, this table tracks what you’ve added, when you added it, and its processing status.
  • Vector Database: Stores embeddings and chunks for semantic search
  • Contents Database: Tracks content metadata, status, and when coupled with AgentOS Knowledge, provides management of your knowledge via API.

​
Why Use ContentsDB?

​
Content Visibility and Control

Without ContentsDB, managing your knowledge and vectors is difficult - you can search it, but you can’t manage individual pieces of content or alter all the vectors created from a single piece of content. With ContentsDB, you gain full visibility:
  • See all content that has been added
  • Track processing status of each item
  • View metadata and file information
  • Monitor access patterns and usage

​
Powerful Management Capabilities

  • Edit names, descriptions and metadata for existing content
  • Delete specific content and automatically clean up associated vectors
  • Update content without rebuilding the entire knowledge base
  • Batch operations for managing multiple content items
  • Status tracking to monitor processing success/failure

​
Required for AgentOS

If you’re using AgentOS, ContentsDB is mandatory for the Knowledge page functionality. The AgentOS web interface relies on ContentsDB to display and manage your knowledge content.

​
Setting Up ContentsDB

​
Choose Your Database

Agno supports multiple database backends for ContentsDB:
  • PostgreSQL - Recommended for production
  • SQLite - Great for development and single-user applications
  • MySQL - Enterprise-ready relational database
  • MongoDB - Document-based NoSQL option
  • Redis - In-memory option for high performance
  • In-Memory - Temporary storage for testing
  • Cloud Options - DynamoDB, Firestore, GCS

​
Basic Setup Example

from agno.knowledge import Knowledge
from agno.db.postgres import PostgresDb
from agno.vectordb.pgvector import PgVector

# Set up ContentsDB - tracks content metadata
contents_db = PostgresDb(
    db_url="postgresql+psycopg://user:pass@localhost:5432/db",
    knowledge_table="knowledge_contents"  # Optional: custom table name
)

# Set up vector database - stores embeddings
vector_db = PgVector(
    table_name="vectors",
    db_url="postgresql+psycopg://user:pass@localhost:5432/db"
)

# Create Knowledge with both databases
knowledge = Knowledge(
    name="My Knowledge Base",
    vector_db=vector_db,
    contents_db=contents_db  # This enables content tracking!
)

​
Alternative Database Examples

# SQLite for development
from agno.db.sqlite import SqliteDb
contents_db = SqliteDb(db_file="my_knowledge.db")

# MongoDB for document-based storage
from agno.db.mongo import MongoDb
contents_db = MongoDb(
    uri="mongodb://localhost:27017",
    database="agno_db"
)

# In-memory for testing
from agno.db.in_memory import InMemoryDb
contents_db = InMemoryDb()

​
Core Functionality

​
Contents DB Schema

If you have a Contents DB configured for your Knowledge, the content metadata will be stored in a contents table in your database. The schema for the contents table is as follows:
FieldTypeDescription
idstrThe unique identifier for the content.
namestrThe name of the content.
descriptionstrThe description of the content.
metadatadictThe metadata for the content.
typestrThe type of the content.
sizeintThe size of the content. Applicable only to files.
linked_tostrThe ID of the content that this content is linked to.
access_countintThe number of times this content has been accessed.
statusstrThe status of the content.
status_messagestrThe message associated with the status of the content.
created_atintThe timestamp when the content was created.
updated_atintThe timestamp when the content was last updated.
external_idstrThe external ID of the content. Used when external vector stores are used, like LightRAG.
This data is best displayed on the knowledge page of the AgentOS UI.

​
Content Metadata Tracking

# When you add content
knowledge.add_content(
    name="Product Manual",
    path="docs/manual.pdf",
    metadata={"department": "engineering", "version": "2.1"}
)

# ContentsDB automatically stores all the fields from the schema above
# - External IDs for cloud integrations

​
Content Retrieval and Management

# Get all content with pagination
contents, total_count = knowledge.get_content(
    limit=20,
    page=1,
    sort_by="created_at",
    sort_order="desc"
)

# Get specific content by ID
content = knowledge.get_content_by_id(content_id)

# Each content object includes:
print(content.name)         # Content name
print(content.description)  # Description
print(content.metadata)     # Custom metadata
print(content.file_type)    # File type (.pdf, .txt, etc.)
print(content.size)         # File size in bytes
print(content.status)       # Processing status
print(content.created_at)   # When it was added
print(content.updated_at)   # Last modification

​
Management Features

​
Content Deletion with Vector Cleanup

Delete content and automatically clean up associated vectors: This automatically:
  1. Removes the content metadata from ContentsDB
  2. Deletes associated vectors from the vector database
  3. Maintains consistency between both databases
# Delete specific content
knowledge.remove_content_by_id(content_id)

# Delete all content
knowledge.remove_all_content()
ContentsDB enables powerful filtering capabilities: 
# The knowledge base tracks valid filter keys
valid_filters = knowledge.get_filters()

# Filter content during search
results = knowledge.search(
    query="technical documentation",
    filters={"department": "engineering", "version": "2.1"}
)

​
AgentOS Integration

​
Required Setup for AgentOS

When using AgentOS, ContentsDB is mandatory for the Knowledge management interface: 
from agno.os import AgentOS
from agno.db.postgres import PostgresDb
from agno.agent import Agent

# ContentsDB is required for AgentOS Knowledge page
contents_db = PostgresDb(
    db_url="postgresql+psycopg://user:pass@localhost:5432/db"
)

vector_db = PgVector(table_name="vectors", db_url="http://my-postgress:5432")


knowledge = Knowledge(
    vector_db=vector_db,
    contents_db=contents_db  # Must be provided for AgentOS
)

knowledge_agent = Agent(
    name="Knowledge Agent",
    knowledge=knowledge
)

# Create AgentOS app
app = AgentOS(
    description="Example app for basic agent with knowledge capabilities",
    os_id="knowledge-demo",
    agents=[knowledge_agent],
)

​
AgentOS Features Enabled by ContentsDB

With ContentsDB, the AgentOS Knowledge page provides:
  • Content Browser: View all uploaded content with metadata
  • Upload Interface: Add new content through the web UI
  • Status Monitoring: Real-time processing status updates
  • Metadata Editor: Update content metadata through forms
  • Content Management: Delete or modify content entries
  • Search and Filtering: Find content by metadata attributes
  • Bulk Operations: Manage multiple content items at once
Check out the AgentOS Knowledge page for more in-depth information.

​
Next Steps