This release is a pre-release and may not be stable for production use.
EverMem
md-first memory extraction framework for AI agents — lightweight, single-user or small-team.
What is EverMem
EverMem is an open-source Python framework that turns conversations / workflows / files into structured, retrievable, evolving long-term memory for AI agents. Designed for lightweight local deployments (personal agents, small teams, individual developers), with three core principles:
- Markdown as Source of Truth — All memory persists as plain
.mdfiles. Open, edit, grep, version with Git, view in Obsidian. No black-box database lock-in. - Lightweight three-piece storage —
Markdownfiles (truth) +SQLite(state/queue) +LanceDB(vector + BM25 + scalar). No MongoDB / Elasticsearch / Milvus / Redis / Kafka required. - EverCore as pure algorithm library — Memory extraction algorithms are decoupled into a separate library; this project orchestrates and persists.
Architecture at a glance
┌───────────────────────────────────────────────┐
│ entrypoints/ (CLI + HTTP API) │ presentation
├───────────────────────────────────────────────┤
│ service/ (use cases: memorize/retrieve) │ application
├───────────────────────────────────────────────┤
│ memory/ (extract + search + cascade) │ domain
├───────────────────────────────────────────────┤
│ infra/ (markdown / sqlite / lancedb) │ infrastructure
└───────────────────────────────────────────────┘
↑ ↑
component/ core/
(LLM/Embedding) (observability/lifespan)
DDD 5 layers, single-direction dependency. See docs/architecture.md.
Quick start
Install as a package
uv pip install evermem # or: pip install evermem
# Drop a .env in your working directory.
# OpenAI-protocol compatible — works with OpenAI, OpenRouter, vLLM, Ollama, ...
cat > .env <<'EOF'
# LLM
EVERMEM_LLM__MODEL=gpt-4o-mini
EVERMEM_LLM__API_KEY=sk-...
EVERMEM_LLM__BASE_URL=https://api.openai.com/v1
# Embedding
EVERMEM_EMBEDDING__MODEL=Qwen/Qwen3-Embedding-4B
EVERMEM_EMBEDDING__API_KEY=...
EVERMEM_EMBEDDING__BASE_URL=https://api.deepinfra.com/v1/openai
# Rerank
EVERMEM_RERANK__MODEL=Qwen/Qwen3-Reranker-4B
EVERMEM_RERANK__API_KEY=...
EVERMEM_RERANK__BASE_URL=https://api.deepinfra.com/v1/inference
EOF
evermem --help
evermem server start
For a step-by-step walkthrough (add a conversation → flush → search → read the markdown), see QUICKSTART.md.
Develop locally
git clone <repo>
cd evermem
uv sync # creates ./.venv and installs deps
source .venv/bin/activate # — or skip activation and prefix every command with `uv run`
cp env.template .env # fill in EVERMEM_LLM__API_KEY
evermem --help
make test
Storage layout
~/.evermem/
├── memory/ # Markdown — Single Source of Truth
│ ├── users/<user_id>/
│ │ ├── user.md # profile
│ │ ├── memcells/ # day-level append logs
│ │ ├── episodic/
│ │ └── ...
│ └── agents/<agent_id>/
│ ├── agent.md
│ ├── cases/
│ └── skills/
├── .index/ # LanceDB derived indexes (rebuildable)
└── .system.db # SQLite: state + audit + queue + metadata
Open the memory/ folder in Obsidian — your agent's brain is just files.
Features
- Hybrid retrieval: BM25 + vector (HNSW/IVF-PQ) + scalar filter, single-query in LanceDB
- Cascade index sync: edit a
.md→ file watcher → entry-level diff → LanceDB sync, sub-second - Multi-source extraction: conversations / workflows / agent traces / file knowledge
- Dual-track memory: user-track (Episodes / Profiles) + agent-track (Cases / Skills)
- Async-first: full asyncio, single event loop
- Multi-modal: text + small image / audio inline; large media via S3/OSS reference
Project structure
evermem/ # repo root
├── src/evermem/ # main package (src layout)
│ ├── entrypoints/ # cli + api
│ ├── service/ # use case orchestration
│ ├── memory/ # domain: extract + search + cascade + prompt_slots
│ ├── infra/ # storage: markdown + lancedb + sqlite
│ ├── component/ # cross-cutting: llm / embedding / config / utils
│ ├── core/ # runtime: observability / lifespan / context
│ └── config/ # configuration data + Settings schema
├── tests/ # unit / integration / golden / fixtures
├── docs/ # design docs
├── examples/ # quickstart + chat_agent + obsidian_demo
└── .claude/ # team-shared rules + skills (auto-loaded by Claude Code)
Documentation
- docs/overview.md — Project overview & vision
- docs/architecture.md — DDD layered architecture & dependency rules
- docs/engineering.md — Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code)
- CHANGELOG.md — Release notes
- CONTRIBUTING.md — How to contribute
- .claude/rules/ — Detailed coding conventions (auto-loaded by Claude Code)
Status
Alpha (v0.1.0) — Active development. Core API may change before v1.0.
License
Apache License 2.0 — see NOTICE for third-party attributions.
Citation
If you use EverMem in research, see CITATION.md.
Acknowledgments: This project builds on prior research and tooling — see ACKNOWLEDGMENTS.md.
Metadata
Release files for evermem 0.1.0rc5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| evermem-0.1.0rc5.tar.gz | 1.3 MB | Without provenance | Details for evermem-0.1.0rc5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| evermem-0.1.0rc5-py3-none-any.whl | Python 3 | none | any | Details for evermem-0.1.0rc5-py3-none-any.whl |
Total release size: 1.7 MB
Release files / evermem-0.1.0rc5.tar.gz
| Download URL | evermem-0.1.0rc5.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d93116a1cc9e3fac91ed80f3101fa67dba8ba6b2785c995a9e70cf46d840c8d4
|
|
BLAKE2b-256 checksum How to use checksums |
6f95047165f88085382a1838746998758925b0e622a2b9c31430e392e4083905
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / evermem-0.1.0rc5-py3-none-any.whl
| Download URL | evermem-0.1.0rc5-py3-none-any.whl |
|---|---|
| Size | 388.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7c7d611a38283f44d64f7b8a6f36152d13742a2d8dc3d771fbd17c0cd12ece98
|
|
BLAKE2b-256 checksum How to use checksums |
5df93d06f4a89b056bd8d26afa70fe089b1f792f2b2f5c50138b4b9a659f7ad3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for evermem 0.1.0rc5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.