Metadata-Version: 2.4
Name: evermem
Version: 0.1.0rc4
Summary: EverMem — md-first memory extraction framework (lightweight; single-user or small-team)
Author: EverMind AI
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,evermem,lancedb,markdown,memory,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: anyio>=4.0
Requires-Dist: apscheduler<4.0,>=3.10.4
Requires-Dist: everalgo-agent-memory==0.2.0
Requires-Dist: everalgo-boundary==0.2.0
Requires-Dist: everalgo-core==0.2.0
Requires-Dist: everalgo-rank==0.3.0
Requires-Dist: everalgo-user-memory==0.2.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: greenlet>=3.0
Requires-Dist: jieba==0.42.1
Requires-Dist: lancedb>=0.13.0
Requires-Dist: openai>=1.0.0
Requires-Dist: portalocker>=2.8.2
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.7.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: structlog>=24.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: watchfiles>=0.21.0
Provides-Extra: multimodal
Requires-Dist: everalgo-parser[svg]>=0.1.0; extra == 'multimodal'
Description-Content-Type: text/markdown

# EverMem

> md-first memory extraction framework for AI agents — lightweight, single-user or small-team.

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)

---

## 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](docs/architecture.md).

## Quick start

### Install as a package

```bash
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](QUICKSTART.md).

### Develop locally

```bash
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](docs/overview.md) — Project overview & vision
- [docs/architecture.md](docs/architecture.md) — DDD layered architecture & dependency rules
- [docs/engineering.md](docs/engineering.md) — Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code)
- [CHANGELOG.md](CHANGELOG.md) — Release notes
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute
- [.claude/rules/](.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](LICENSE) — see [NOTICE](NOTICE) for third-party attributions.

## Citation

If you use EverMem in research, see [CITATION.md](CITATION.md).

---

**Acknowledgments**: This project builds on prior research and tooling — see [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
