evermem 0.1.0rc4

EverMem — md-first memory extraction framework (lightweight; single-user or small-team)

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:

1. Markdown as Source of Truth — All memory persists as plain .md files. Open, edit, grep, version with Git, view in Obsidian. No black-box database lock-in.
2. Lightweight three-piece storage — Markdown files (truth) + SQLite (state/queue) + LanceDB (vector + BM25 + scalar). No MongoDB / Elasticsearch / Milvus / Redis / Kafka required.
3. 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.