LLMem is a SQLite-backed memory store for LLM agents. It provides structured storage with full-text search (FTS5), optional vector similarity search (via sqlite-vec), an extensible type system, and a provider abstraction layer for LLM embeddings and text generation. A background dreaming cycle consolidates, decays, and merges memories over time.
See CONTRIBUTING.md for development setup and coding conventions.
| Document | Description |
|---|---|
| Installation | Install from source (Python and Go), optional extras, plugin setup |
| Providers | Embedding/generation providers, fallback chains, configuration |
| CLI Reference | All llmem commands and options |
| Python API | MemoryStore, Retriever, extension points, database schema, module reference |
| Go API | Go packages — store, config, dream, extract, introspect, ollama, paths, session, systemd, taxonomy, urlvalidate |
| Integrations | OpenCode, Copilot CLI, custom tools, session hooks |
| Configuration | config.yaml reference, path resolution, dream settings |
| Search Reranking | Multi-signal reranking, signal weights, type priority |
| Dream Cycle & Extraction | Dream phases, extraction pipeline, session hooks |
| Security | Path validation, SSRF protection, credential handling, code indexing security |
Quick install:
curl -sSL https://raw.githubusercontent.com/MichielDean/LLMem/main/setup.sh | bashOr clone and run locally:
git clone https://github.com/MichielDean/LLMem.git
cd LLMem && ./setup.shFor detailed installation options (extras, plugins, requirements), see docs/INSTALLATION.md.
The Go implementation provides the core memory store as a pure-Go library with no CGo dependency, plus a full CLI, dream cycle, session hooks, introspection, and extraction:
go get github.com/MichielDean/LLMemimport (
"github.com/MichielDean/LLMem/internal/store"
"github.com/MichielDean/LLMem/internal/embed"
"github.com/MichielDean/LLMem/internal/retriever"
"github.com/MichielDean/LLMem/internal/metrics"
"github.com/MichielDean/LLMem/internal/urlvalidate"
)
ms, err := store.NewMemoryStore(store.StoreConfig{
DBPath: "", // defaults to ~/.config/llmem/memory.db
VecDimensions: 0, // defaults to 768
DisableVec: false, // set true to skip vec0 virtual table
RegisteredTypes: nil, // defaults to 8 standard types
})
if err != nil {
log.Fatal(err)
}
defer ms.Close()
// Embedding engine (Ollama client with LRU cache)
eng, err := embed.NewEmbeddingEngine(embed.EmbeddingConfig{})
// Hybrid search retriever (FTS5 + semantic with RRF fusion)
r, err := retriever.NewRetriever(retriever.RetrieverConfig{Store: ms, Embedder: eng})
// Embedding quality metrics
m, err := metrics.ComputeMetrics(embeddings, labels, 0)
// SSRF-protected URL validation
safe := urlvalidate.IsSafeURL(urlStr, false)See docs/INSTALLATION.md for Go build dependencies and docs/API.md for the full API reference.
LLMem ships four skills focused on memory management. Agent workflow skills (git-sync, task-intake, test-and-verify, branch-strategy, critical-code-reviewer, pre-pr-review, visual-explainer) are distributed separately as part of agent harnesses.
| Skill | Description |
|---|---|
| llmem | Manage LLMem memories — add, search, consolidate, dream, introspect, and track review outcomes. |
| llmem-setup | Install and configure LLMem for an agent harness — provider setup, skill registration, harness integration. |
| introspection | Operational reference for the introspection framework — self-assessment, sampajanna checks, error taxonomy. |
| introspection-review-tracker | Reference for the automated ReviewOutcomeTracker hook that persists review findings as self_assessment memories. |
The templates/ directory contains generic, personality-agnostic template files that you can copy and customize for your own agent setup:
| Template | Purpose |
|---|---|
| templates/rules.md | Generic workflow rules — no personal or tool-specific references |
| templates/identity.md | Agent identity scaffold — fill in your agent's name, personality, and boundaries |
| templates/user.md | User profile scaffold — fill in your name, timezone, and preferences |
To use them, copy the templates into your harness/ directory and fill them in:
cp templates/identity.md harness/identity.md
cp templates/user.md harness/user.md
cp templates/rules.md harness/rules.md
# Then edit each file to personalize for your setupThe opencode.json configuration loads harness/identity.md, harness/user.md, and harness/rules.md — so after copying and customizing, your agent will use your personalized versions.
After installing from source, verify everything works:
# Check the CLI is available
llmem --help
# Initialize config and database
llmem init
# Confirm the store is working
llmem stats
# Verify skills are discoverable (OpenCode plugin only)
ls ~/.agents/skills/llmem ~/.agents/skills/introspection ~/.agents/skills/git-sync# Initialize the memory system (creates config, database, detects providers)
llmem init
# Non-interactive mode (skip prompts, use defaults)
llmem init --non-interactive
# Add a memory
llmem add --type fact --content "Project uses pytest for testing"
# Search memories
llmem search "testing"
llmem search "testing" --type fact --limit 5 --json
llmem search "testing" --include-code --json
# Index a codebase
llmem learn ./src
llmem learn ./src --strategy fixed --window-size 30 --overlap 5
llmem learn ./src --no-embed
# List all memories
llmem list
llmem list --type decision --all
# Get a specific memory
llmem get <memory-id>
# Show statistics
llmem stats
# Register a custom memory type
llmem register-type my_custom_type
llmem types
# Working memory inbox
llmem note "Important observation from today's session"
llmem note "Tentative insight" --attention-score 0.3
llmem inbox
llmem consolidate --dry-run
llmem consolidate --min-score 0.5
# Dream cycle (automated memory maintenance)
llmem dream # Dry run — preview changes only
llmem dream --apply # Apply changes
llmem dream --phase deep # Run only the deep phase
llmem dream --report dream.html # Generate HTML dream report
# Check embedding quality
llmem embed
llmem consolidate --metrics
# Export and import
llmem export --output backup.json
llmem import backup.json# Python tests
python -m pytest
# Go tests
go test ./...1349 Python tests and 142 JavaScript tests covering all providers, session adapters (OpenCode, Copilot, none), URL validation, configuration, security, session hooks, CLI commands, and edge cases.
Go tests covering store operations, FTS5 search, vector search, hybrid retrieval, embedding engine, metrics, URL validation, migrations, type validation, import/export, config, dream cycle, extraction, introspection, session hooks, path validation, systemd unit generation, and taxonomy.
The Go project includes a Makefile with common tasks:
make build # go build ./...
make test # go test ./...
make lint # go vet ./...
make clean # remove *.db filesMIT