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 |
Clone and build:
git clone https://github.com/MichielDean/LLMem.git
cd LLMem && make buildThis produces the llmem CLI binary. Install it on your PATH:
make install # copies to ~/.local/bin/llmemOr install manually:
cp llmem ~/.local/bin/llmem
ln -sf ~/.local/bin/llmem /usr/local/bin/llmem # optional, for system-wide accessThen initialize:
llmem init # interactive — detects providers
llmem init --non-interactive # use defaults, no promptsFor detailed installation options (Python extras, providers, requirements), see docs/INSTALLATION.md.
After building the CLI, install the agent integration layer:
cd LLMem && npm installThis runs the postinstall script which:
- Copies 4 skill directories to
~/.agents/skills/ - Auto-detects your agent platform (OpenCode, Claude Code, or Copilot CLI)
- Deploys the correct plugin to the right location
Force a specific platform:
node install.js --platform opencode # OpenCode only
node install.js --platform claude-code # Claude Code / Copilot CLI
node install.js --platform copilot # Copilot CLI (same plugin as claude-code)
node install.js --platform both # OpenCode + Claude Code / Copilot CLI
node install.js --platform none # Skills only, no pluginsSee below for per-platform setup details.
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 uses platform plugins to inject memory context automatically. No manual instruction editing required. The plugin handles:
- Session start: Injects memory stats, behavioral patterns, and proposed procedures as context
- Session idle/end: Extracts memories from the session transcript
- Compaction: Preserves key memories across context compaction
| Platform | Plugin | How to install |
|---|---|---|
| OpenCode | plugins/opencode/llmem.js |
Auto-deployed by npm install to ~/.config/opencode/plugins/ |
| Claude Code | plugins/agent/ |
claude plugin install ~/.claude/plugins/llmem (auto-deployed by npm install) |
| Copilot CLI | plugins/agent/ |
Same plugin as Claude Code — both use the .claude-plugin format |
Claude Code and GitHub Copilot CLI share the same plugin (plugins/agent/) because they use the same plugin specification. The plugin bundles hooks for SessionStart, SessionEnd, and PreCompact, plus all four LLMem skills.
The plugin-first approach means your AGENTS.md, CLAUDE.md, or system instructions stay clean — no 80-line memory blocks. See Integrations for platform-specific setup.
LLMem ships four skills focused on memory management. They load on-demand via the skill system — no need to paste their content into instruction files.
| Skill | Description |
|---|---|
| llmem | Manage LLMem memories — add, search, consolidate, dream, introspect, and track review outcomes. |
| llmem-setup | Install and configure LLMem — plugin deployment, provider setup, skill registration. |
| 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, 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 deployed
ls ~/.agents/skills/llmem ~/.agents/skills/introspection
# Verify plugin deployed (OpenCode)
ls ~/.config/opencode/plugins/llmem.js
# Verify plugin deployed (Claude Code / Copilot CLI)
ls ~/.claude/plugins/llmem/.claude-plugin/plugin.json# 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