README
¶
Creel
Self-hosted memory-as-a-service for AI agents.
v0.5.x: CompactionService (sync/async compaction, undo, history), chunk linking (LinkService), managed document pipeline, semantic chunking, per-principal memory, dashboard, creel-chat.
Creel provides topic-scoped memory with principal-based RBAC, server-side document processing, per-principal memory (Mem0-style), and dual-mode retrieval (semantic search with citations + temporal context). Upload documents and Creel handles extraction, chunking, and embedding automatically. It runs in your infrastructure via Helm chart.
Quick start
# Start PostgreSQL + Creel server
docker compose up -d
# Build the CLI tools
make build
# Source the dev environment (sets CREEL_ENDPOINT and CREEL_API_KEY)
source .env
# Create a topic and upload a document
bin/creel-cli topic create --slug my-notes --name "My Notes"
bin/creel-cli upload --topic my-notes --file notes.txt --name "Meeting Notes"
# Check processing status
bin/creel-cli jobs list --topic my-notes
# Search (once processing completes)
bin/creel-cli search --topic my-notes --query "action items" --top-k 5
See Quickstart for the full walkthrough.
Key features
- Upload and forget: upload PDFs, HTML, or plain text; Creel extracts text, chunks it (fixed-size or LLM-based semantic), and embeds in the background
- Document citations: search results include document metadata (title, author, URL, date) for proper attribution
- Per-principal memory: automatic fact extraction from conversations with Mem0-style conflict resolution (ADD/UPDATE/DELETE/NOOP)
- Topic > Document > Chunk hierarchy with RBAC and cross-topic linking
- Dual-mode retrieval: RAG (semantic search) and context (temporal ordering)
- Server-driven compaction with link preservation
- Pluggable vector backends: pgvector (reference), OpenAI, Qdrant, Weaviate
- 63 gRPC/REST RPCs across 10 services
- Two ingestion paths: managed (upload and forget) and direct (pre-chunked, pre-embedded) for power users
- Admin dashboard: Laravel-based web UI for config, topic, system account, and memory management
- creel-chat: interactive demo agent with streaming, memory, cross-topic RAG, and citation display
Documentation
| Guide | Description |
|---|---|
| Quickstart | End-to-end setup in under 5 minutes |
| Fullstart | Hands-on walkthrough of every feature |
| Concepts | Data model, auth, search modes, memory, document processing |
| API Reference | All 63 RPCs with request/response details |
| Development | Dev environment, testing, adding RPCs and workers |
| Deployment | Helm chart, configuration, OIDC setup |
| creel-chat | Interactive demo agent with conversation memory |
| Architecture | Full design document and roadmap |
Status
Active development (v0.4.x). Phases 1-5 complete plus PDF extraction, semantic chunking, dashboard memory browser, and chunk linking (LinkService). Phases 6, 8-9 (integration layers, compaction, additional backends) are next. See docs/ARCHITECTURE.md for the roadmap and CHANGELOG.md for release history.
License
Apache 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
creel
command
|
|
|
creel-chat
command
|
|
|
creel-cli
command
|
|
|
internal
|
|
|
auth
Package auth provides authentication and authorization for Creel.
|
Package auth provides authentication and authorization for Creel. |
|
config
Package config handles loading and validating Creel server configuration.
|
Package config handles loading and validating Creel server configuration. |
|
crypto
Package crypto provides AES-256-GCM encryption for sensitive configuration values.
|
Package crypto provides AES-256-GCM encryption for sensitive configuration values. |
|
fetch
Package fetch provides an interface and implementations for fetching remote content.
|
Package fetch provides an interface and implementations for fetching remote content. |
|
llm
Package llm provides interfaces and implementations for LLM interactions.
|
Package llm provides interfaces and implementations for LLM interactions. |
|
retrieval
Package retrieval implements RAG search logic for Creel.
|
Package retrieval implements RAG search logic for Creel. |
|
server
Package server implements the Creel gRPC server.
|
Package server implements the Creel gRPC server. |
|
slug
Package slug provides URL-friendly slug generation from names.
|
Package slug provides URL-friendly slug generation from names. |
|
store
Package store provides PostgreSQL-backed data access for Creel.
|
Package store provides PostgreSQL-backed data access for Creel. |
|
store/dbtest
Package dbtest provides test helpers for database stores.
|
Package dbtest provides test helpers for database stores. |
|
vector
Package vector defines the interface for pluggable vector storage backends.
|
Package vector defines the interface for pluggable vector storage backends. |
|
vector/pgvector
Package pgvector implements the vector.Backend interface using PostgreSQL with pgvector.
|
Package pgvector implements the vector.Backend interface using PostgreSQL with pgvector. |
|
vector/vectortest
Package vectortest provides a reusable conformance test suite for vector backends.
|
Package vectortest provides a reusable conformance test suite for vector backends. |
|
worker
Package worker provides a background job processing pool.
|
Package worker provides a background job processing pool. |
|
Package mcp implements the Creel MCP server adapter.
|
Package mcp implements the Creel MCP server adapter. |
Click to show internal directories.
Click to hide internal directories.