# EverOS: a Markdown-first memory layer for AI agents

> EverOS is a Python library and local-first memory runtime from EverMind AI that keeps agent and user memory as readable Markdown files, with SQLite and LanceDB indexes built on top. It suits developers who want to inspect and version what their agent remembers, and it is not a drop-in hosted memory API.

**EverMind-AI/EverOS** — One portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.

- Repository: https://github.com/EverMind-AI/EverOS
- Website: https://evermind.ai/everos
- Stars: 13,322 · Forks: 924
- Language: Python
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/evermind-ai-everos

## What problem EverOS targets, and for whom

Most agent frameworks treat memory as a database row or a vector namespace. The README positions EverOS against that: the canonical store is a set of .md files that are, in its words, "readable, editable, diffable, and Git-versioned", while SQLite and LanceDB hold indexes for retrieval. The comparison table in the README draws the line at "Markdown source of truth" and "Direct file editing": other agent memory libraries, it argues, keep state in an API, a vector store, a graph, a dashboard or a database.

That choice defines the audience. If you are a developer working alone or on a small team, running an agent locally and wanting to see exactly what it learned in the last session, a folder of Markdown is easier to reason about than a managed vector service. The pyproject.toml describes the project as "lightweight, dev-friendly, small-team". The three-part local stack (Markdown plus SQLite plus LanceDB) means no MongoDB, Elasticsearch or Redis is required, which matters if you do not want to operate infrastructure to get persistent memory.

The second audience is anyone who has to separate what the user remembers from what the agent has learned. EverOS keeps user episodes and profiles on one track and agent cases and skills on another, and the README calls these "separate first-class surfaces". That is a real distinction: a coding assistant's accumulated technique is not the same thing as a user's stated preferences, and collapsing them into one profile blob makes both harder to audit.

## How the storage and retrieval stack fits together

The README describes the flow as ingest, extract, index, recall. Conversations, files and agent trajectories arrive as Markdown; a watcher detects edits to those files and cascades the changes into the indexes, so editing a .md file by hand is a supported update path rather than a corruption risk. Retrieval then runs against SQLite and LanceDB, where LanceDB handles vector search, BM25 full-text search and scalar filtering on Arrow data.

The dependency list in pyproject.toml reveals how tightly the project is bound to LanceDB. The pin is `lancedb>=0.34.0,<0.35.0`, and the comment above it is unusually candid: version 0.32 to 0.34 carry a "compaction offset-overflow regression", and the project runs 0.34.0 with a workaround described as the `with_position=False` FTS setting. The same comment warns against floating past 0.34.x until 0.35 has been validated under sustained churn, and against ever widening the floor back below 0.34 because older LanceDB cannot read v8 data. That is the kind of constraint you want stated in a manifest rather than discovered in production.

Retrieval is deliberately orthogonal. The README lists search by `user_id`, `agent_id`, `app_id`, `project_id` and `session_id`, which lets one memory store serve several apps and several agents without a namespace per tenant. Reflection runs offline between sessions, merging clusters of episodes and refining profiles and skills. The README frames this as the difference from retrieval-only memory, and it is the part of the design that most affects how useful the store becomes over time.

## Installing EverOS and running a first memory round trip

The README requires Python 3.12 or newer and one OpenRouter API key. Installation is a single package install, with uv or pip both listed.

```bash
uv pip install everos
# or: pip install everos
```

Before configuring anything, the README offers a demo that needs no key and no server. It walks memory through the four stages so you can watch a fact you typed come back out.

```bash
everos demo
```

If you cloned the repository and have not activated a virtual environment, the README gives `uv run everos demo` instead. Next, initialize the configuration. This writes two files, and the README says the generated model and OpenRouter URL are already correct.

```bash
everos init
```

The command creates `~/.everos/everos.toml` and `~/.everos/ome.toml`. Open the first one and replace only the empty `api_key` value.

```toml
[llm]
model = "openai/gpt-4.1-mini"
api_key = "<OPENROUTER_API_KEY>"
base_url = "https://openrouter.ai/api/v1"
```

The README calls this the smallest Tier 1 setup: memory add, flush, Markdown persistence, cascade indexing and keyword search. If you want the memory root somewhere else, `everos init --root <path>` changes it, and the README notes you must pass the same `--root <path>` to later commands. Finally, start the server and check it from a second terminal.

```bash
everos server start
```

```bash
curl http://127.0.0.1:8000/health
```

The response should contain `"status":"ok"`. Note what the README says about capabilities in that same setup: `capabilities.llm` is true, while embedding and rerank remain false until you configure them. Keyword search works at this tier; vector retrieval does not.

## Where the local-first design costs you

The Markdown-first design has a price, and the README does not hide the shape of it. Because the files are the source of truth and a watcher cascades edits into the indexes, correctness depends on that cascade running. If the watcher is not running, or a write lands while it is down, the index and the files can disagree, and the README's own comparison table presents direct file editing as an advantage without describing reconciliation. The project ships a `docs/cascade_runbook.md`, referenced from the LanceDB pin comment, which suggests the maintainers treat cascade behaviour as an operational concern rather than an implementation detail.

The LanceDB constraint is the second cost. The dependency comment describes a compaction regression in the 0.32 to 0.34 range and a workaround tied to `with_position=False` for full-text search. A team that wants to upgrade LanceDB on its own schedule cannot simply float the version: the comment warns that older LanceDB cannot read v8 data, so the floor is one-way. This is a project where you inherit its storage engine's release cadence.

The third cost is scope. EverOS runs as a local server that you start and keep running, and the quick start assumes a single machine with a memory root under `~/.everos`. Nothing in the README describes a hosted or multi-tenant deployment. If your agents run in ephemeral containers, or you need memory shared across machines without shipping the Markdown directory around, this is the wrong tool and the README does not claim otherwise. The project is also Python-only: `requires-python = ">=3.12"` in pyproject.toml, so a Node or Go agent has to reach memory over the HTTP server rather than in-process.

## How EverOS differs from a hosted memory API

The obvious alternative is a managed memory service, where you send conversation turns to an endpoint and query them back later. The difference is not feature parity; it is where the canonical data lives. With a hosted service, the record of what your agent remembers sits behind someone else's API, and correcting a wrong memory usually means calling an update method or opening a dashboard. With EverOS, the record is a `.md` file, and the README's claim is that editing it is enough because the cascade watcher picks up the change.

That changes the failure and recovery story. A hosted service gives you availability guarantees and no files to lose; EverOS gives you files you can back up, diff and review in a pull request, but it also gives you a directory that can be deleted, a watcher that can be stopped, and an index that can drift. The README's orthogonal retrieval keys are the other real difference: scoping by `user_id`, `agent_id`, `app_id`, `project_id` and `session_id` in one store is a different model from per-tenant namespaces, and it is what makes a single local memory usable across several apps and agents.

A second alternative is building memory directly on a vector database plus a profile table. That gets you retrieval, but the README's reflection feature, offline merging of episode clusters with profile and skill refinement, has no equivalent in a plain vector store. Whether reflection earns its complexity depends on how long your agent runs and how much its behaviour should change between sessions.

## Licence, releases and what upgrades involve

EverOS is Apache-2.0, stated in both the README badge area and pyproject.toml, with a LICENSE and NOTICE file at the repository root. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve the licence and notice files when redistributing. That is a summary of the licence text, not legal advice, and if you ship EverOS inside a product you should read the LICENSE and NOTICE files yourself.

The release cadence is visible in the tags: v1.3.0 on 2026-09-07, v1.3.1 on 2026-09-08, following v1.2.3 on 2026-08-07. The last push to the default branch was on 2026-09-09, so the repository is current. Upgrades are not just a version bump, though. Because the LanceDB pin is bounded and the comment warns that older LanceDB cannot read v8 data, a downgrade is not a safe rollback path for the index. The repository also carries Alembic for SQLite schema migrations, so a version change can involve a migration step as well as a package install. The README does not document rollback, and there is no published downgrade procedure in the repository files; if reversibility matters to you, treat that as an open question to resolve before you depend on it.

## Conclusion

Adopt EverOS if you want agent memory you can open in an editor, diff in Git, and search by user_id, agent_id, app_id, project_id and session_id without running MongoDB, Elasticsearch or Redis. Do not adopt it if you need a hosted, multi-tenant memory service or you cannot run a local server and a Python 3.12+ process next to your agent. Before committing, verify that the OpenRouter key you configure works against the model named in ~/.everos/everos.toml, and check whether you need the embedding and rerank capabilities that the README says stay false after the one-key setup.

## FAQ

### How do I install EverOS?

The README requires Python 3.12 or newer and gives two equivalent commands: `uv pip install everos` or `pip install everos`. After installing, `everos demo` runs without an API key so you can see the ingest, extract, index and recall cycle before configuring anything.

### What is EverOS?

EverOS is a Python library and local-first memory runtime for agents and makers. It stores conversations, files and agent trajectories as Markdown, then syncs local SQLite and LanceDB indexes for retrieval, with user episodes and profiles kept separate from agent cases and skills.

### Does EverOS need an API key to get started?

The demo does not: the README says it needs no API key or server setup. To move past the demo, `everos init` creates `~/.everos/everos.toml` and you replace the empty `api_key` with an OpenRouter key, which is the only credential the quick start asks for.

## Sources

- [EverMind-AI/EverOS on GitHub](https://github.com/EverMind-AI/EverOS)
- [License: Apache-2.0](https://github.com/EverMind-AI/EverOS/blob/main/LICENSE)
- [Project website](https://evermind.ai/everos)
- [README](https://github.com/EverMind-AI/EverOS/blob/main/README.md)
- [Releases](https://github.com/EverMind-AI/EverOS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/evermind-ai-everos