Metadata-Version: 2.5
Name: memvault-cli
Version: 0.1.0
Summary: File-first memory engine: inbox ingestion, hybrid retrieval, weekly reflection
Project-URL: Homepage, https://github.com/emre6943/memvault
Project-URL: Repository, https://github.com/emre6943/memvault
Project-URL: Issues, https://github.com/emre6943/memvault/issues
License-Expression: MIT
License-File: LICENSE
Keywords: markdown,mcp,memory,notes,rag,retrieval,vault
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp<2.1,>=2.0.0
Requires-Dist: numpy<2.3,>=1.26
Requires-Dist: pyyaml>=6.0
Provides-Extra: semantic
Requires-Dist: fastembed>=0.4; extra == 'semantic'
Description-Content-Type: text/markdown

# MemVault

A file-first memory engine. Everything you learn, say, or are told enters through one inbox, gets
classified and filed into a vault of plain Markdown, and becomes retrievable by meaning instead of
by recency.

Every memory is a file. Every automated change is a git diff you can read and revert.

## How it works

```
SOURCES            INBOX           ENGINE                    VAULT
glasses ────┐                  ┌─ normalize                transcripts/
claude.ai ──┼──▶ inbox/ ──────▶├─ classify (LLM)   ──────▶ memory/
manual ─────┘    (git)         ├─ route                    repos/<name>/
                               ├─ distill                  index/vault.db
                               └─ index
```

Drop any text into `inbox/` and commit — from a laptop, or from a phone with an iOS git client.
The ingestion pass classifies it, files it into the vault with provenance, updates the search
index, and commits. The inbox drains to empty; a non-empty inbox means work is pending.

A weekly pass reads what arrived, curates it into durable memory, and writes a digest. A `/recall`
skill answers questions against the whole vault so sessions fetch depth on demand rather than
loading memory in bulk at startup.

## Engine and vault are separate

MemVault is the engine — code, no content. A **vault** is a separate git repo holding your
Markdown. The engine reads a config naming your vault's paths and routes, so one install serves
several vaults (for example, a personal one and a work one) with no code changes.

## Install

```bash
uv tool install "memvault-cli[semantic]"    # recommended
uv tool install memvault-cli                # light: keyword search only
```

The `semantic` extra pulls `fastembed` and downloads a ~130MB multilingual model on first index.
Without it everything still works and every file is still indexed — `recall` runs the keyword
half alone and says so in its own output, so half a search never reads like a whole one. Adding
the extra later is `memvault index` again.

Working on the engine itself instead? `uv sync` and prefix the commands below with `uv run`.

## Commands

```bash
memvault init ~/my-vault   # scaffold a vault (or adopt notes you already keep) + config
memvault doctor            # vault health; exits non-zero on problems
memvault ingest            # drain the inbox into the vault, then commit
memvault index             # build or update the search index
memvault recall "query"    # hybrid keyword + semantic search
memvault reflect           # weekly curation pass over recent material
memvault mcp ~/my-vault    # serve the vault over MCP (Codex, opencode, Cursor, …)
```

`memvault init` prints the exact wiring line for each harness once your vault exists.

Ingest can also run itself a few quiet minutes after you stop working, instead of on a clock. A
SessionStart hook runs `memvault ingest --session-start <id>` and a SessionEnd hook runs
`memvault ingest --enqueue`; a plain `memvault ingest` from a scheduled job stays the safety net
and services whatever the queue is still asking for. See `debounce:` in the example config.

`--vault <name>` picks a configured vault. Start with [`SETUP.md`](SETUP.md).

## Status

**Implemented and verified end to end**, and in daily use. `ruff` and `mypy --strict` clean.

Verified against a real vault rather than only in tests — a dropped note was classified, filed
with provenance, and committed with the inbox drained; a work-flavored drop produced a distilled
note in the second vault with no verbatim sentence crossing; re-running produced no duplicate.

- Requirements: [`docs/brainstorms/2026-08-01-memvault-requirements.md`](docs/brainstorms/2026-08-01-memvault-requirements.md)
- Plans: [`docs/plans/`](docs/plans/)
- Inbox contract, for building feeders: [`docs/inbox-contract.md`](docs/inbox-contract.md)
- Before this repo goes public: [`docs/release-audit-checklist.md`](docs/release-audit-checklist.md)

## License

MIT — see [`LICENSE`](LICENSE).
