Skip to main content
Glama
Strata Memory MCP Server

Strata Memory MCP Server

by SherryLi-vc
README.md
# strata-memory

<p align="center">
  <a href="./assets/brand/README.md">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./assets/brand/extensions/lockup_dark_transparent.svg">
      <img alt="strata-memory" src="./assets/brand/extensions/lockup_light_transparent.svg" width="420">
    </picture>
  </a>
</p>

[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.org)

English · [简体中文](README.zh-CN.md)

**It remembers why you decided.**

When a fact changes, strata does not overwrite the row. The previous memory is archived and linked (`supersedes_id` / `superseded_by`). A `decision_record` keeps the choice, the date, and what it replaced, so a later session can explain why the current fact is the current fact.

```json
{
  "user_id": "user_001",
  "memory_type": "decision_record",
  "fact_claim": "On 2026-08-10 the team decided SQLite is the memory source of truth, replacing the Markdown drawers.",
  "confidence_score": 0.95
}
```

Recall returns a short card. `expand_memory_detail` loads the chain: the new claim, `supersedes_id`, and the archived predecessor.

---

## Quickstart

Python 3.11+ and [uv](https://docs.astral.sh/uv/). No API key. Text stays on the machine.

```bash
uvx --from git+https://github.com/SherryLi-vc/strata-memory strata-memory-mcp
```

PyPI install (`uvx strata-memory-mcp`) is coming soon; it does not work until the first release is published. The PyPI project name will be `strata-memory-mcp`. `strata-memory` on PyPI is a different package. Do not install that name.

That starts the MCP server on stdio. Data lives in `STRATA_PALACE` (default `~/.strata/palace`). A new palace defaults to the local embedder. A `config.json` that already names a provider is left alone. Host snippets do not set `STRATA_EMBEDDING_PROVIDER`, because an environment value overrides the saved palace.

Print a snippet for your host and merge it into the existing config. Do not replace the rest of the file.

```bash
uvx --from git+https://github.com/SherryLi-vc/strata-memory strata-memory-mcp setup --host cursor
uvx --from git+https://github.com/SherryLi-vc/strata-memory strata-memory-mcp setup --host claude-code
uvx --from git+https://github.com/SherryLi-vc/strata-memory strata-memory-mcp setup --host claude-desktop
```

| Host | Config |
|------|--------|
| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
| Claude Code | `.mcp.json` or `mcpServers` in `~/.claude.json` |
| Claude Desktop | Settings → Developer → Edit Config |
| Hermes | `~/.hermes/config.yaml` — see [skills/strata-memory/references/hermes-config.yaml](skills/strata-memory/references/hermes-config.yaml) |

Cursor example (`setup --host cursor`):

```json
{
  "mcpServers": {
    "strata-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SherryLi-vc/strata-memory", "strata-memory-mcp"],
      "env": {
        "STRATA_PALACE": "${userHome}/.strata/palace"
      }
    }
  }
}
```

Claude Desktop's snippet is the same shape and is valid JSON. Desktop does not expand `${VAR}`; edit the palace path in that file if you need to. Once the package is on PyPI (coming soon), `args` can shrink to `["strata-memory-mcp"]`.

Then call `strata_init` once and `strata_doctor`. Both report the effective embedding provider, model, and backend. With the default provider, `summary.api_key.usable` is true because no key is required.

## Examples

Commit a preference:

```json
{
  "user_id": "user_001",
  "memory_type": "user_preference",
  "fact_claim": "User prefers the Monokai Pro theme with dark mode in VS Code.",
  "confidence_score": 0.92
}
```

Recall cards. `limit` applies to L0, scratch, and every other tier. `include_l0` defaults to true.

```json
{
  "user_id": "user_001",
  "query": "Monokai Pro theme dark mode",
  "limit": 3,
  "include_l0": true
}
```

Expand one id:

```json
{ "user_id": "user_001", "memory_id": "<id from hits>" }
```

Forget one memory, or a filtered set. A filter does nothing until `confirm` is true. The row is removed from SQLite and from the vector index, so `strata_rebuild_index` cannot bring it back.

```json
{ "user_id": "user_001", "memory_id": "<id>" }
```

```json
{ "user_id": "user_001", "memory_type": "episodic_event", "confirm": true }
```

Export JSON (MCP `export_memories`, or the CLI):

```bash
uvx --from git+https://github.com/SherryLi-vc/strata-memory strata-memory-mcp export --user user_001 --out memories.json
```

## What the default embedder is

`local` tries fastembed, then sentence-transformers. If neither is installed, it uses a deterministic hashing embedder: offline, no download, no key. Hashing matches shared words. It does not match paraphrases. `scripts/recall_benchmark.py` reports literal-overlap and paraphrase scores separately, and it runs the semantic backend only when fastembed is installed.

For a semantic model:

```bash
uvx --from 'strata-memory-mcp[local] @ git+https://github.com/SherryLi-vc/strata-memory' strata-memory-mcp
```

That pulls the optional `local` extra (fastembed / ONNX). The first run downloads `sentence-transformers/all-MiniLM-L6-v2` and needs a network. Offline, that download fails quickly and tells you to set `STRATA_LOCAL_EMBED_BACKEND=hash` (or `STRATA_EMBEDDING_HASH_FALLBACK=1`) instead of hanging. After a successful download the weights stay on the machine. The index stores the embedder identity. A provider or model change refuses vector reads and writes until `strata_rebuild_index(confirm=true)`.

Cloud endpoints are opt-in. They receive memory text and recall queries.

| Variable | Role |
|----------|------|
| `STRATA_EMBEDDING_PROVIDER` | `local` (default), `siliconflow`, `openai`, `openai_compatible` |
| `STRATA_EMBEDDING_BASE_URL` | OpenAI-compatible `POST /embeddings` root. SiliconFlow is `https://api.siliconflow.cn/v1` |
| `STRATA_EMBEDDING_MODEL` | Model id |
| `STRATA_EMBEDDING_DIMENSION` | Vector length. Default 384 |
| `STRATA_EMBEDDING_API_KEY` or `STRATA_API_KEY` | Required for non-loopback HTTP providers |

A `config.json` that already names `siliconflow` keeps that provider. Set `STRATA_EMBEDDING_PROVIDER=local` to switch, then rebuild.

## Tools (13)

| Tool | Use |
|------|-----|
| `strata_init` | Create the palace and SQLite store |
| `commit_memory` | Write one vetted fact |
| `promote_session` | Promote that session's scratch rows |
| `recall_context` | Ranked cards. `limit` covers every tier. `include_l0` controls L0 |
| `expand_memory_detail` | Full text for one id |
| `forget_memory` | Delete by id, or by filter with `confirm=true` |
| `export_memories` | JSON for one user and tenant |
| `strata_doctor` | SQLite vs index, and whether a key is required |
| `strata_rebuild_index` | Rebuild vectors from SQLite. `confirm=true` |
| `strata_stats` | Layer counts |
| `strata_project` | Read-only Markdown view |
| `strata_digest` | Demote or archive. Default dry-run |
| `strata_hygiene` | Expired rows, hash duplicates, secret scan |

`memory_type` is `factual_truth`, `user_preference`, `procedure_rule`, `episodic_event`, or `decision_record`. The first three default to L0.

## FAQ

**Where do memories live?**  
SQLite under `STRATA_PALACE` (default `~/.strata/palace`) stores the source of truth and rebuildable vector index. Markdown from `strata_project` is a read-only view.

**Does this phone home?**  
Not with the default `local` provider. A cloud provider or a non-loopback `STRATA_EMBEDDING_BASE_URL` receives memory text and queries.

**Why is a fact different from last month?**  
Look at `decision_record` rows and at `supersedes_id` / `superseded_by` on the expanded card. The old row is archived, not destroyed, unless you `forget_memory`.

**Can I delete something?**  
Yes. `forget_memory` by id, or by `memory_type` / `layer` / `session_id` / `query` with `confirm=true`. Deletion is scoped to `user_id` and `tenant_id`. A rebuild will not restore deleted rows.

**How do I back up?**  
`export_memories` or `strata-memory export --user USER --out memories.json`. `strata_project` is the Markdown view of the same store.

**Does recall dump the whole palace?**  
No. You pass a query and a `limit` (1–20). L0 facts, preferences, and procedures are ranked against that query. They are not pinned to the front of the list with a score of 1.

**Will it store a password or an API key?**  
No. By default `commit_memory` masks a detected secret before anything is stored, embedded or audited: `key AKIA…` becomes `key [redacted:aws_access_key_id]`, and the response lists what was masked in `secrets_redacted`. Set `"on_secret": "reject"` in the palace `config.json` (or `STRATA_ON_SECRET=reject`) to refuse such writes with `SECRET_DETECTED` instead. Detection is pattern-based (cloud and API keys, tokens, private keys, JWTs, passwords, credentials in URLs), so it can miss a secret with no recognizable shape. The quality kernel also rejects emotion-only text, fuzzy times (`yesterday`, `刚才`), and speculation stored as `factual_truth`. Other memory tools also block or redact secrets; this is a write-time check, not a claim that the feature is unique.

**The doctor says the key is missing.**  
You selected a cloud provider. Set the key in the host environment, not in chat. Or switch `STRATA_EMBEDDING_PROVIDER` back to `local`.

## Breaking changes in 2.2

- New installs default to `STRATA_EMBEDDING_PROVIDER=local`. A saved `config.json` that names `siliconflow` (or another provider) is unchanged. A palace file with no embedding block stays on SiliconFlow, which was the historical default.
- `recall_context` ranks L0 and scratch with everything else and applies `limit` to that list. Scores are no longer a constant 1.0. `include_l0` is on the MCP tool (default true). `current_turn_only` still leaves L0 out.
- The distribution name is `strata-memory-mcp`. `uvx strata-memory` installs a different project.

## Upgrading from an older version

Indexes built before 2.2.1 have no embedder stamp (`l2_vector/embedder.json`). After upgrading:

1. `recall_context` keeps working, but on the lexical path only. The reply carries `fusion.vector_skipped = "EMBEDDER_UNSTAMPED"` and a warning. `commit_memory` still writes to SQLite; it skips the vector until the index is stamped.
2. Run `strata_rebuild_index` with `confirm=true` once. It re-embeds every active memory from SQLite and writes the stamp. With a cloud provider this re-embeds every row, which costs API calls.
3. Run `strata_doctor`. `embedder_stamp` and `vector_coverage` should both be ok.

`strata_rebuild_index` without `tenant_id` rebuilds every tenant. With `tenant_id` it deletes and re-adds only that tenant's vectors; other tenants are untouched. If the index is unstamped or was built by another embedder, a tenant-scoped call rebuilds all tenants instead (`scope: "all"`, `escalated_from_tenant`), because the other vectors are unusable anyway. Changing the embedding provider or model still requires a rebuild before vector recall resumes (`EMBEDDER_MISMATCH`).

## Known issues

- The default install embeds with an offline hashing fallback, which matches shared words, not meaning. Install the `local` extra (fastembed) for semantic recall.

## Develop

```bash
git clone https://github.com/SherryLi-vc/strata-memory.git
cd strata-memory
uv sync --extra dev
uv run pytest -v
uv run python scripts/recall_benchmark.py
```

Packaging check: `uv build` and `uvx twine check dist/*`. Publishing is a maintainer action through PyPI Trusted Publishing (see DEVELOPMENT.md, "Releasing"). This repo does not contain a PyPI token.

Architecture: [docs/architecture.md](docs/architecture.md) · Tools: [docs/tools.md](docs/tools.md) · Security: [SECURITY.md](SECURITY.md) · 中文: [README.zh-CN.md](README.zh-CN.md)

## License

MIT — see [LICENSE](LICENSE)

TDQS

A3.7/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct purpose: initialization, health, profiling, memory writing, searching, recommendations, and session wake-up. No two tools have overlapping functionality that would confuse an agent.

Naming Consistency4/5

Most tools follow a verb_noun pattern (e.g., apply_memory_config, get_health, search_embedding_recommendations). However, 'strata_init' reverses the order (noun_verb) and 'memorize' is a lone verb without an object, causing slight inconsistency.

Tool Count5/5

With 8 tools, the surface is well-scoped and balanced for a memory management server. Each tool earns its place and covers core workflows without being excessively large or minimal.

Completeness3/5

The server covers initialization, health, profiling, memorizing, searching, and session wake-up, but lacks update and delete operations for memories. This gap may cause agents to fail when they need to modify or remove stored data.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues