Meniscus gives AI tools a shared local memory. It turns useful context into compact facts surfaces the minimum amount of memory sufficient for a query. Every connected agent reads and writes the same SQLite file.

AI agents ───┐
Code editors ┼── MCP ── Meniscus ── ~/.meniscus/meniscus.db
Local tools ─┘

Install

Meniscus requires Python 3.11 or newer and an API key for any supported language-model provider. Embeddings run locally; there is no embedding service or embedding key to configure.

uv tool install "meniscus[all]"
men init

men init does the rest:

1. asks which model provider you want to use;
2. recommends a model or lets you enter another model ID;
3. verifies the key and model before saving them;
4. initializes the local database and embedding model;
5. offers background capture; and
6. connects detected AI tools over MCP.

Nothing is uploaded to a Meniscus server. Configuration and credentials stay under ~/.meniscus/; the API key is sent only to the provider you select.

Try it

Add something directly:

men add "Chose SQLite for Fernwind because it needs zero operations and one-file backups."

Ask for it later:

men ask "What storage did I choose for Fernwind, and why?"

Or ask from a connected agent. It receives two MCP tools:

• meniscus_recall retrieves relevant memory.
• meniscus_log stores something worth remembering.

MCP setup

Meniscus works with any client that can run a local stdio MCP server, including Claude Code, Codex, Antigravity, Cursor, and Windsurf. men init automatically configures clients whose command-line tools it detects; other clients only need the men-mcp executable path.

Check an existing connection with:

claude mcp list
codex mcp list

If Claude says MCP server meniscus already exists in local config, Meniscus is already registered for that project. Do not add it again. If the listed server is healthy, restart Claude Code and continue.

If that existing entry points to an old or missing executable, replace it:

claude mcp remove --scope local meniscus
claude mcp add --scope user meniscus -- "$(command -v men-mcp)"

If you skipped connection during initialization, add it manually:

claude mcp add --scope user meniscus -- "$(command -v men-mcp)"
codex mcp add meniscus -- "$(command -v men-mcp)"

The absolute executable path matters for GUI applications that do not inherit your shell PATH.

command -v men-mcp

{
  "mcpServers": {
    "meniscus": {
      "command": "/absolute/path/to/men-mcp"
    }
  }
}

Commands

Setup and health

Capture and recall

Session capture

Without --distill, men watch safely stores raw events as pending. Run men process later to turn them into searchable facts.

--start and --stop control background capture. The other flags run capture in your terminal for as long as the command lasts.

Passive transcript adapters currently recognize Claude Code and Codex session files. Every MCP-compatible client can still recall and log memory through meniscus_recall and meniscus_log.

Inspect your memory

Run men [COMMAND] --help for every option accepted by a command.

Where data lives

Supported model providers

men init supports OpenRouter, OpenAI, Anthropic, Google Gemini, Groq, xAI, Hugging Face Inference Providers, Ollama, and custom OpenAI-compatible endpoints. Meniscus uses the same selected model for memory processing and men ask synthesis.

If processing becomes unavailable, captured events remain pending instead of being discarded. Fix the provider with men config set, verify it with men doctor, then resume with men process.

Background capture

Background capture keeps men watch running, so Claude Code and Codex sessions are recorded without you starting anything. men init offers to install it, and it can be switched on or off at any time:

men watch --start    # start capturing in the background
men watch --stop     # stop capturing

Both commands report what actually happened, and capture stays off after --stop until you start it again.

If memory seems to have stopped growing, men status shows how long ago the last event landed and men doctor checks that the database still accepts new events.

How retrieval works

session or imported text
        ↓
append-only raw event
        ↓
compact facts + local embeddings + entity anchors
        ↓
deterministic fusion of semantic, keyword, and entity retrieval
        ↓
minimum relevant memory returned to the agent

Meniscus uses an LLM only to interpret and compact language and, optionally, to synthesize the final men ask answer. Storage, provenance, indexing, candidate fusion, and the final retrieval cut are ordinary code.

Benchmarks

Measured on a 100-instance stratified sample of LongMemEval-S:

The answer score uses a strong reader. A small local reader scored approximately 54%; the published oracle ceiling using perfect retrieval was approximately 82%. The remaining weakness is multi-session aggregation.

The benchmark inputs, frozen memories, and commands are documented in bench/README.md.

Development

git clone https://github.com/magic-bubblez/meniscus.git
cd meniscus
uv sync --all-extras
uv run pytest -q

Meniscus is alpha software. Before upgrading, copy ~/.meniscus/meniscus.db if the memory matters to you.

License

MIT