Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dallay/corvus/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Corvus implements a full-stack memory system with zero external dependencies. All components (vector search, keyword search, embedding cache) are built-in and optimized for performance.

​
Memory Backends

Corvus supports multiple memory backends with identical API:

SQLite (Default)

Hybrid vector + keyword search with FTS5Best for: Most use cases, production deployments

SurrealDB

Distributed graph database backendBest for: Multi-agent systems, shared memory

Markdown

Flat-file storage for simple setupsBest for: Development, testing, portability

None

Explicit no-op memory (disabled)Best for: Stateless agents, temporary instances
Default memory backend with hybrid search: 
[memory]
backend = "sqlite"
auto_save = true

# Embedding configuration
embedding_provider = "openai"
embedding_model = "text-embedding-3-small"
embedding_dimensions = 1536

# Hybrid search weights
vector_weight = 0.7
keyword_weight = 0.3
min_relevance_score = 0.4

# Cache settings
embedding_cache_size = 10000
chunk_max_tokens = 512

​
Architecture

LayerImplementation
Vector DBEmbeddings stored as BLOB, cosine similarity search
Keyword SearchFTS5 virtual tables with BM25 scoring
Hybrid MergeCustom weighted merge function
EmbeddingsOpenAI or custom endpoint
ChunkingLine-based with heading preservation
CachingLRU cache with 10,000 entry limit

​
Configuration Fields

​
memory.backend
string
default:"sqlite"
Memory backend: sqlite, surreal, markdown, or none.
​
memory.auto_save
boolean
default:true
Automatically save conversation context to memory.
​
memory.embedding_provider
string
default:"none"
Embedding provider:
  • openai: OpenAI embeddings API
  • custom:https://your-api.com: Custom endpoint
  • none: Disable embeddings (keyword-only search)
​
memory.embedding_model
string
default:"text-embedding-3-small"
Embedding model name.
​
memory.embedding_dimensions
number
default:1536
Embedding vector dimensions.
​
memory.vector_weight
number
Weight for vector similarity in hybrid search (0.0-1.0).
​
memory.keyword_weight
number
Weight for keyword BM25 in hybrid search (0.0-1.0).
​
memory.min_relevance_score
number
Minimum hybrid score (0.0-1.0) for a memory to be included in context.Memories scoring below this threshold are dropped to prevent irrelevant context bleeding.
​
memory.embedding_cache_size
number
default:10000
Maximum embedding cache entries before LRU eviction.
​
memory.chunk_max_tokens
number
default:512
Maximum tokens per chunk for document splitting.

​
SurrealDB Backend

Distributed memory backend for multi-agent systems: 
[memory]
backend = "surreal"
auto_save = true

[memory.surreal]
url = "http://127.0.0.1:8000"
namespace = "corvus"
database = "memory"

# Authentication (choose one)
username = "corvus"
password = "corvus-pass"
# OR
token = "jwt-token..."

allow_http_loopback = true  # Allow HTTP for localhost only

​
Environment Variables

export CORVUS_MEMORY_BACKEND=surreal
export CORVUS_SURREALDB_URL=http://127.0.0.1:8000
export CORVUS_SURREALDB_NAMESPACE=corvus
export CORVUS_SURREALDB_DATABASE=memory
export CORVUS_SURREALDB_USERNAME=corvus
export CORVUS_SURREALDB_PASSWORD=your-password
# OR
export CORVUS_SURREALDB_TOKEN=jwt-token...

​
Configuration Fields

​
memory.surreal.url
string
SurrealDB endpoint URL:
  • HTTP: http://127.0.0.1:8000
  • WebSocket: ws://127.0.0.1:8000/rpc
​
memory.surreal.namespace
string
default:"corvus"
SurrealDB namespace.
​
memory.surreal.database
string
default:"memory"
SurrealDB database name.
​
memory.surreal.username
string
Username for authentication (ignored if token is set).
​
memory.surreal.password
string
Password for authentication (ignored if token is set).
​
memory.surreal.token
string
JWT token for authentication (preferred over username/password).
​
memory.surreal.allow_http_loopback
boolean
default:true
Allow plain HTTP for loopback addresses only (127.0.0.1, ::1).Non-loopback HTTP URLs are rejected unless this is false and the URL is HTTPS.

​
Markdown Backend

Flat-file storage for simple setups: 
[memory]
backend = "markdown"
auto_save = true
Memories are stored as markdown files in ~/.corvus/workspace/memory/.

​
Memory Hygiene

Automatic memory management to prevent unbounded growth: 
[memory]
hygiene_enabled = true
archive_after_days = 7
purge_after_days = 30
conversation_retention_days = 30
​
memory.hygiene_enabled
boolean
default:true
Run automatic memory hygiene (archiving + retention cleanup).
​
memory.archive_after_days
number
default:7
Archive daily/session files older than N days.
​
memory.purge_after_days
number
default:30
Purge archived files older than N days.
​
memory.conversation_retention_days
number
default:30
For SQLite backend: prune conversation rows older than N days.

​
Response Caching

Cache LLM responses to save tokens on repeated prompts: 
[memory]
response_cache_enabled = true
response_cache_ttl_minutes = 60
response_cache_max_entries = 5000
​
memory.response_cache_enabled
boolean
default:false
Enable LLM response caching to avoid paying for duplicate prompts.
​
memory.response_cache_ttl_minutes
number
default:60
TTL in minutes for cached responses.
​
memory.response_cache_max_entries
number
default:5000
Maximum cached responses before LRU eviction.

​
Memory Snapshots

Periodic export of core memories to Markdown: 
[memory]
snapshot_enabled = true
snapshot_on_hygiene = true
auto_hydrate = true
​
memory.snapshot_enabled
boolean
default:false
Enable periodic export of core memories to MEMORY_SNAPSHOT.md.
​
memory.snapshot_on_hygiene
boolean
default:false
Run snapshot during hygiene passes (heartbeat-driven).
​
memory.auto_hydrate
boolean
default:true
Auto-hydrate from MEMORY_SNAPSHOT.md when brain.db is missing.

​
SQLite Advanced Settings

[memory]
sqlite_open_timeout_secs = 300  # Max seconds to wait for DB lock
​
memory.sqlite_open_timeout_secs
number
Maximum seconds to wait when opening the database (e.g., file locked).
  • None: Wait indefinitely (default)
  • Recommended max: 300 (5 minutes)

​
Memory Tools

The agent automatically uses these tools to manage memory:
ToolDescription
memory_storeSave information to long-term memory
memory_recallSearch memory using hybrid vector + keyword search
memory_forgetDelete specific memories
Example agent usage: 
corvus agent -m "Remember that my favorite color is blue"
# Agent uses memory_store internally

corvus agent -m "What's my favorite color?"
# Agent uses memory_recall internally

​
Complete Example

[memory]
# Backend selection
backend = "sqlite"
auto_save = true

# Embedding configuration
embedding_provider = "openai"
embedding_model = "text-embedding-3-small"
embedding_dimensions = 1536

# Hybrid search weights
vector_weight = 0.7
keyword_weight = 0.3
min_relevance_score = 0.4

# Cache settings
embedding_cache_size = 10000
chunk_max_tokens = 512

# Memory hygiene
hygiene_enabled = true
archive_after_days = 7
purge_after_days = 30
conversation_retention_days = 30

# Response caching
response_cache_enabled = true
response_cache_ttl_minutes = 60
response_cache_max_entries = 5000

# Memory snapshots
snapshot_enabled = true
snapshot_on_hygiene = true
auto_hydrate = true

# SQLite settings
sqlite_open_timeout_secs = 300

# SurrealDB settings (if backend = "surreal")
[memory.surreal]
url = "http://127.0.0.1:8000"
namespace = "corvus"
database = "memory"
username = "corvus"
password = "corvus-pass"
allow_http_loopback = true

​
Migration from OpenClaw

Migrate existing OpenClaw memories: 
# Preview migration (dry run)
corvus migrate openclaw --dry-run

# Perform migration
corvus migrate openclaw
This imports:
  • Identity and soul definitions
  • Conversation history
  • Long-term memories
  • User preferences

​
Next Steps

Security Configuration

Configure gateway security, autonomy levels, and runtime isolation

Build docs developers (and LLMs) love

Get started for freeTalk to us