Content
<div align="center">
<pre>
███╗ ███╗██╗███╗ ██╗██╗ ██████╗ ███╗ ██╗ ██████╗ ███████╗
████╗ ████║██║████╗ ██║██║██╔═══██╗████╗ ██║██╔═══██╗██╔════╝
██╔████╔██║██║██╔██╗ ██║██║██║ ██║██╔██╗ ██║██║ ██║███████╗
██║╚██╔╝██║██║██║╚██╗██║██║██║ ██║██║╚██╗██║██║ ██║╚════██║
██║ ╚═╝ ██║██║██║ ╚████║██║╚██████╔╝██║ ╚████║╚██████╔╝███████║
╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝ ╚══════╝
</pre>
<p>
<a href="https://github.com/Catafal/MinionOS/actions/workflows/ci.yml">
<img src="https://github.com/Catafal/MinionOS/actions/workflows/ci.yml/badge.svg" alt="CI">
</a>
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License">
</a>
</p>
</div>
> Local-first memory for AI agents
Your AI agents forget everything between sessions. MinionOS fixes that. Feed it text, it extracts entities, relationships, and facts into a local SQLite knowledge graph, then surfaces the right context when your agents need it.
Nothing leaves your machine unless you point it at a remote LLM.
---
## Quick start
```bash
# Install
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Set up
memos onboard
# Store your first memory
memos remember "Met with Sarah about the Q3 roadmap. She's concerned about the timeline." --domain job
# Find it later
memos search "roadmap"
```
---
## What you can do
**Store knowledge** — feed any free-text and an LLM pulls out entities, relationships, and facts automatically:
```bash
memos remember "Started reading DDIA, chapter on replication" --domain side-projects
memos remember "Jake moved to the infra team last week" --domain job
cat meeting-notes.txt | memos remember --stdin --domain job
```
**Search your graph** — BM25 + graph-augmented retrieval, scoped by domain:
```bash
memos search "replication"
memos search "Jake" --domain job --limit 5
memos --format json search "Python" | jq '.[].name'
```
**Inject context into agents** — bundle relevant entities + recent facts into a payload:
```bash
memos context "current work" --format json
memos context "Python" --domain job --days 3 --format json | agent --context -
```
**Ask questions** — get answers grounded in your knowledge graph:
```bash
memos ask "What did Sarah say about the timeline?"
```
**Track trends** — see which entities are rising, stable, or going quiet:
```bash
memos trends --domain job
```
---
## MCP server
`memos-mcp` exposes the knowledge graph as an [MCP](https://modelcontextprotocol.io/) tool. Any agent that speaks MCP can read and write your memory directly.
```bash
memos-mcp
```
Point your MCP-compatible agent at it and it gets `search`, `remember`, `context`, and `ask` as tools.
---
## Obsidian sync
The graph can live as `.md` entity files in your Obsidian vault. Edit in Obsidian, sync back:
```bash
# Add your vault
memos vault add my-notes ~/Documents/my-notes
# Sync vault edits into the SQLite index
memos sync
# Insert [[wikilinks]] between related entities
memos link
```
You can register multiple vaults. Each one maps to a domain.
---
## Background minions
14 autonomous workers that consolidate facts, link entities, detect contradictions, prune stale edges, and embed facts for semantic search. They run on a schedule so the graph stays healthy without manual work.
```bash
# Run all maintenance tasks once
memos heartbeat run
# Set up automatic scheduling (launchd on macOS, systemd on Linux)
memos heartbeat install
# Check what's running
memos heartbeat status
```
Each minion task can be configured individually in `~/.minionOS/config.yaml` — enable/disable, set frequency, adjust the heartbeat interval.
---
## Using Ollama (fully local, no API key)
```bash
ollama serve
ollama pull llama3.1
memos config set llm_base_url http://localhost:11434/v1
memos config set llm_model llama3.1
```
Everything stays on your machine. No API key required.
---
## Troubleshooting
Run diagnostics first:
```bash
memos doctor # 11 checks: config, API, database, vaults, services
memos doctor --fix # Auto-repair what it can
```
| Problem | Fix |
|---------|-----|
| No API key | `memos onboard` or `export OPENROUTER_API_KEY="sk-or-v1-..."` |
| Database missing | `memos doctor --fix` rebuilds it |
| Vault not syncing | `memos vault list` to verify paths, then `memos sync` |
| Heartbeat not running | `memos heartbeat install` |
| LLM extraction fails | Text is queued automatically and retried on next heartbeat |
---
## All commands
```
memos remember "text" Store knowledge via LLM extraction
memos search "query" BM25 + graph search
memos context "topic" Bundle context for agent injection
memos ask "question" Question answering over the graph
memos trends Entity mention trends over time
memos recap Narrative summary of recent activity
memos digest Summarize recent graph activity
memos onboard Full guided setup (recommended)
memos init Add vaults to existing install
memos status System state: config, vaults, DB, LLM
memos doctor Health checks with auto-fix
memos vault add/list/remove Manage vaults
memos sync Sync vault edits into SQLite
memos link Insert [[wikilinks]] into vault files
memos heartbeat run Run all minions once
memos heartbeat install Schedule automatic runs
memos dashboard Live minion status display
memos integrate Render agent integration prompt
memos config View or modify configuration
```
All commands support `--format json` for machine-readable output.
---
## Prerequisites
| Requirement | Notes |
|-------------|-------|
| Python 3.11+ | Uses modern type union syntax |
| OpenRouter API key | For LLM extraction. Free at [openrouter.ai/keys](https://openrouter.ai/keys). Or use Ollama locally. |
| Ollama *(optional)* | Fully local LLM — no API key, no network calls |
---
## Development
### Setup
```bash
git clone https://github.com/Catafal/MinionOS.git
cd MinionOS
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### Quality gate
```bash
make gate # ruff + mypy + pytest (run before every commit)
make test # pytest with coverage
make fix # auto-fix lint and formatting
make lint # ruff check + format verification
make type # mypy strict type checking
```
### Project structure
```
MinionOS/
├── src/minionos/
│ ├── cli/ # Click CLI commands
│ ├── minions/ # 14 autonomous background workers
│ ├── integrations/ # Agent integration layer
│ ├── prompts/ # LLM prompt templates
│ ├── skills/ # Heartbeat skill definitions
│ ├── api.py # Public API (CLI and MCP call this)
│ ├── db.py # SQLite schema + queries
│ ├── retrieval.py # BM25 + vector + RRF ranking
│ ├── graph.py # Entity/relationship graph ops
│ ├── llm.py # LLM client (OpenRouter, Ollama, Gemini)
│ ├── config.py # YAML config loader
│ ├── vault.py # Obsidian vault read/write
│ └── mcp_server.py # MCP server entry point
├── tests/ # 1,000+ tests
├── docs/ # Full documentation (Diataxis framework)
└── memory/decisions/ # Architecture decision records
```
### For AI agents working on this codebase
Minimal read path (~2,500 tokens total):
1. `CLAUDE.md` — conventions, layer rules, commands
2. `docs/index.md` — component status + quick routes
3. `docs/graph/catalog.yaml` — full doc index
4. The specific doc you need
---
## Documentation
| Topic | File |
|-------|------|
| CLI usage (setup, commands, scripting) | [docs/backend/how-to/using-the-cli.md](docs/backend/how-to/using-the-cli.md) |
| CLI command reference (options, exit codes) | [docs/backend/reference/cli-reference.md](docs/backend/reference/cli-reference.md) |
| Architecture decisions | [memory/decisions/](memory/decisions/) |
| Backend guided walkthrough | [docs/books/backend.md](docs/books/backend.md) |
| All docs (navigation map) | [docs/backend/NAVIGATION_MAP.md](docs/backend/NAVIGATION_MAP.md) |
| Product requirements | [PRD.md](PRD.md) |
| Tech stack and versions | [TECH_STACK.md](TECH_STACK.md) |
| User flows and error handling | [APP_FLOW.md](APP_FLOW.md) |
---
## Contributing
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, code style, and PR process.
## Security
Report vulnerabilities through [GitHub Security Advisories](https://github.com/Catafal/MinionOS/security/advisories/new). See [SECURITY.md](SECURITY.md) for details.
## License
Apache 2.0 — see [LICENSE](LICENSE).
---
**Your agents remember. You don't have to.**
