Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,8 @@ and perspective layer under recall, and a retrieval-quality gate in CI.
`sentence_transformers`** (`all-MiniLM-L6-v2`, 384-d, CPU) instead of
`vllm_subprocess` (`Qwen3-VL-Embedding-2B`, 2048-d, GPU). Running the embed server
no longer requires a GPU, a CUDA toolchain, or a 2B-parameter download. Install with
the new `local` extra: `pip install "memorylayer-embed-server[local]"`. **GPU
the new `local` extra: `pip install "./memorylayer-embed-server[local]"` from a
repository checkout (the embed server is not published to PyPI). **GPU
deployments must now set `MEMORYLAYER_EMBED_SINGLE_VECTOR_PROVIDER=vllm_subprocess`
explicitly** — and note this changes the vector dimension, which is a property of
stored data (see below).
Expand Down
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ with sync_client() as memory:
- **Document ingestion** -- upload PDFs / DOCX / images and turn them into memories; optional ColPali multi-vector page search via the embed-server peer
- **Repository Planning Graph** -- sync code structure, traverse symbols and dependencies, maintain task overlays, and detect file/symbol conflicts
- **Skills + MCP registries** -- workspace-scoped libraries of agent skills and MCP server entries with 4-tier scope precedence (user / workspace / tenant / global)
- **MCP integration** -- first-class Model Context Protocol server (25 tools by default, 38 in the `full` profile) for Claude Code, Claude Desktop, OpenCode, Cursor, and other MCP-compatible tools
- **MCP integration** -- first-class Model Context Protocol server (28 tools by default, 40 in the `full` profile) for Claude Code, Claude Desktop, OpenCode, Cursor, and other MCP-compatible tools
- **Optional Aether transport** -- run behind an [Aether](https://aetherlayer.ai) mesh for mTLS, signed identity headers, on-behalf-of delegation, durable task scheduling, and cross-datacenter routing

## Packages
Expand All @@ -48,10 +48,10 @@ with sync_client() as memory:
|------------------------------------------------------------------------------|---------|---------------------------------------------------------|
| **[memorylayer-core-python](./memorylayer-core-python)** | `pip install memorylayer-server` | FastAPI server with SQLite + sqlite-vec storage; optional Turso/libSQL backend |
| **[memorylayer-server-rpg-python](./memorylayer-server-rpg-python)** | `pip install memorylayer-server-rpg` | Repository Planning Graph plugin: sync, traversal, overlays, conflicts, maintenance, and enrichment |
| **[memorylayer-embed-server](./memorylayer-embed-server)** | `pip install "memorylayer-embed-server[local]"` | Stateless embedding peer. `[local]` = CPU (sentence-transformers + ColPali); `[gpu]` adds vLLM, OCR, transcription |
| **[memorylayer-embed-server](./memorylayer-embed-server)** | Container image, or `pip install "./memorylayer-embed-server[local]"` from a checkout (not on PyPI) | Stateless embedding peer. `[local]` = CPU (sentence-transformers + ColPali); `[gpu]` adds vLLM, OCR, transcription |
| **[memorylayer-sdk-python](./memorylayer-sdk-python)** | `pip install memorylayer-client` | Python client SDK (async/sync, optional Aether transport) |
| **[memorylayer-sdk-typescript](./memorylayer-sdk-typescript)** | `npm i @scitrera/memorylayer-sdk` | TypeScript/JavaScript client SDK |
| **[memorylayer-mcp-typescript](./memorylayer-mcp-typescript)** | `npm i @scitrera/memorylayer-mcp-server` | MCP server -- 25 tools (default), up to 38 in `full` |
| **[memorylayer-mcp-typescript](./memorylayer-mcp-typescript)** | `npm i @scitrera/memorylayer-mcp-server` | MCP server -- 28 tools (default), up to 40 in `full` |
| **[memorylayer-sdk-langchain-python](./memorylayer-sdk-langchain-python)** | `pip install memorylayer-langchain` | LangChain integration |
| **[memorylayer-sdk-llamaindex-python](./memorylayer-sdk-llamaindex-python)** | `pip install memorylayer-llamaindex` | LlamaIndex integration |
| **[memorylayer-cc-plugin](./memorylayer-cc-plugin)** | see README | Claude Code plugin -- captures memory before compaction |
Expand Down Expand Up @@ -83,8 +83,9 @@ matches on shared words, which is enough to try the API but not for real retriev
quality. The server says so in its startup log. When you want real embeddings:

```bash
# Self-hosted on CPU — no GPU, no API key
pip install "memorylayer-embed-server[local]" && memorylayer-embed serve --port 61051 &
# Self-hosted on CPU — no GPU, no API key (embed-server is not on PyPI:
# install it from a checkout of this repo, or run ghcr.io/scitrera/memorylayer-embed-server)
pip install "./memorylayer-embed-server[local]" && memorylayer-embed serve --port 61051 &
export MEMORYLAYER_EMBEDDING_PROVIDER=embed_server
export MEMORYLAYER_EMBED_SERVER_URL=http://localhost:61051
export MEMORYLAYER_EMBEDDING_DIMENSIONS=384 # must match the embed model
Expand All @@ -96,8 +97,8 @@ export MEMORYLAYER_EMBEDDING_PROVIDER=openai # or google
export MEMORYLAYER_EMBEDDING_OPENAI_API_KEY=sk-...
memorylayer serve

# Self-hosted on GPU — adds vLLM, OCR, transcription
pip install "memorylayer-embed-server[gpu]" && memorylayer-embed serve --port 61051 &
# Self-hosted on GPU — adds vLLM, OCR, transcription (or the latest-cuda13 image)
pip install "./memorylayer-embed-server[gpu]" && memorylayer-embed serve --port 61051 &
```

The CPU option downloads `all-MiniLM-L6-v2` (~90 MB, 384-d) on first use and runs
Expand Down Expand Up @@ -201,7 +202,7 @@ Add `.mcp.json` to your project root:
}
```

The MCP server auto-detects your workspace from the git repo name. Claude gets 25 tools by default (38 in the `full` profile) -- remember, recall, reflect, sessions, context sandbox / RLM, chat threads, and skills/MCP-server registry helpers.
The MCP server auto-detects your workspace from the git repo name. Claude gets 28 tools by default (40 in the `full` profile) -- remember, recall, reflect, sessions, checkpoints and context packs, context sandbox / RLM, chat threads, and skills/MCP-server registry helpers.

For the full Claude Code experience, also install the **[MemoryLayer plugin](./memorylayer-cc-plugin)** which adds pre-compaction memory capture, session briefings, and automatic memory triggers:

Expand Down
10 changes: 6 additions & 4 deletions memorylayer-cc-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,14 @@ Working memory persists within a session and survives context compaction. At ses

### Slash Commands

Claude Code namespaces plugin commands under the plugin name (`memorylayer`), so they run as `/memorylayer:<command>`:

| Command | Description |
|---------|-------------|
| `/memorylayer-status` | Check connection and workspace info |
| `/memorylayer-setup` | Guided setup and troubleshooting |
| `/memorylayer-remember <content>` | Quick memory storage |
| `/memorylayer-recall <query>` | Quick memory search |
| `/memorylayer:status` | Check connection and workspace info |
| `/memorylayer:setup` | Guided setup and troubleshooting |
| `/memorylayer:remember <content>` | Quick memory storage |
| `/memorylayer:recall <query>` | Quick memory search |

### Hooks

Expand Down
16 changes: 8 additions & 8 deletions memorylayer-cc-plugin/commands/recall.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# /memorylayer-recall
# /memorylayer:recall

Quick command to search memories.

## Usage

```
/memorylayer-recall <query>
/memorylayer:recall <query>
```

## Examples

```
/memorylayer-recall database decisions
/memorylayer-recall authentication bugs
/memorylayer-recall user preferences
/memorylayer-recall what do we know about the API
/memorylayer:recall database decisions
/memorylayer:recall authentication bugs
/memorylayer:recall user preferences
/memorylayer:recall what do we know about the API
```

## Behavior
Expand Down Expand Up @@ -50,6 +50,6 @@ No memories found matching "your query"

Try:
- Broader search terms
- Check /memorylayer-status for connection issues
- Use /memorylayer-remember to store new memories
- Check /memorylayer:status for connection issues
- Use /memorylayer:remember to store new memories
```
10 changes: 5 additions & 5 deletions memorylayer-cc-plugin/commands/remember.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# /memorylayer-remember
# /memorylayer:remember

Quick command to store a memory.

## Usage

```
/memorylayer-remember <content>
/memorylayer:remember <content>
```

## Examples

```
/memorylayer-remember We decided to use PostgreSQL for better JSON support
/memorylayer-remember The auth bug was caused by missing token refresh
/memorylayer-remember User prefers detailed commit messages
/memorylayer:remember We decided to use PostgreSQL for better JSON support
/memorylayer:remember The auth bug was caused by missing token refresh
/memorylayer:remember User prefers detailed commit messages
```

## Behavior
Expand Down
4 changes: 2 additions & 2 deletions memorylayer-cc-plugin/commands/setup.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# /memorylayer-setup
# /memorylayer:setup

Automated setup and verification for MemoryLayer.

## Usage

```
/memorylayer-setup
/memorylayer:setup
```

## Behavior
Expand Down
6 changes: 3 additions & 3 deletions memorylayer-cc-plugin/commands/status.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# /memorylayer-status
# /memorylayer:status

Check MemoryLayer connection status and workspace information.

## Usage

```
/memorylayer-status
/memorylayer:status
```

## Behavior
Expand Down Expand Up @@ -56,5 +56,5 @@ Server: NOT CONNECTED
Troubleshooting:
1. Start the server: memorylayer serve
2. Check MEMORYLAYER_URL environment variable
3. Run /memorylayer-setup for guided configuration
3. Run /memorylayer:setup for guided configuration
```
14 changes: 8 additions & 6 deletions memorylayer-core-python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,10 @@ pip install memorylayer-server[openai]
# With Google GenAI embeddings
pip install memorylayer-server[google]

# Self-hosted embeddings: install + run memorylayer-embed-server separately
# (no extras here — the main server only speaks HTTP to embed-server)
# pip install memorylayer-embed-server[gpu]
# Self-hosted embeddings: run memorylayer-embed-server separately (container
# image, or install from a repository checkout — it is not on PyPI; no extras
# here — the main server only speaks HTTP to embed-server)
# pip install "./memorylayer-embed-server[gpu]"

# All cloud embedding providers + LLM + document parsers
pip install memorylayer-server[all]
Expand Down Expand Up @@ -258,9 +259,10 @@ process or container; the main server only speaks HTTP to it. This is what the
published Docker image is pinned to:

```bash
# In a GPU-equipped peer:
pip install memorylayer-embed-server[gpu]
memorylayer-embed-server serve --port 61051
# In a GPU-equipped peer (from a repository checkout; or run the
# ghcr.io/scitrera/memorylayer-embed-server:latest-cuda13 image):
pip install "./memorylayer-embed-server[gpu]"
memorylayer-embed serve --port 61051

# In the main server process:
export MEMORYLAYER_EMBEDDING_PROVIDER=embed_server
Expand Down
25 changes: 17 additions & 8 deletions memorylayer-embed-server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,31 @@ The main `memorylayer-server` core no longer ships any in-process embedding mode

## Installation

`memorylayer-embed-server` is not published to PyPI. Run the container image, or
install it from a checkout of this repository.

```bash
# Container: CPU image (latest) or CUDA 13 image (latest-cuda13)
docker run -p 61051:61051 ghcr.io/scitrera/memorylayer-embed-server:latest

# From a repository checkout
git clone https://github.com/scitrera/memorylayer.git && cd memorylayer

# Local / CPU: sentence-transformers single-vector embeddings (the default provider)
pip install "memorylayer-embed-server[local]"
pip install "./memorylayer-embed-server[local]"

# Core install (server skeleton only — no embedding backend)
pip install memorylayer-embed-server
pip install ./memorylayer-embed-server

# GPU bundle: OCR + vLLM + ColPali
pip install "memorylayer-embed-server[gpu]"
pip install "./memorylayer-embed-server[gpu]"

# Everything: local + GPU + Google embeddings + observability
pip install "memorylayer-embed-server[all]"
pip install "./memorylayer-embed-server[all]"
```

The default single-vector provider is `sentence_transformers`, which needs the
`local` extra. A bare `pip install memorylayer-embed-server` gives you the server
`local` extra. A bare install without extras gives you the server
skeleton with no embedding backend; it starts, but logs an error naming the extra
to install. Pick a different backend with
`MEMORYLAYER_EMBED_SINGLE_VECTOR_PROVIDER` (see [Configuration](#configuration)).
Expand All @@ -40,7 +49,7 @@ Optional extras:
| `all` | `local + gpu + google + observability` |
| `dev` | pytest + ruff |

Visual-tokenizer (Qwen3.5) lives in the proprietary `memorylayer-embed-server-enterprise` package; install that separately if you need it.
The Qwen3.5 visual tokenizer lives in the AGPL-3.0 `memorylayer-embed-server-enterprise` plugin in [scitrera/memorylayer-enterprise](https://github.com/scitrera/memorylayer-enterprise); install it alongside this package if you need it.

## Quick Start

Expand Down Expand Up @@ -91,7 +100,7 @@ Global flag `-v` / `--verbose` enables debug logging.

| Variable | Default | Description |
|----------|---------|-------------|
| `MEMORYLAYER_EMBED_SERVER_HOST` | `127.0.0.1` | Bind address |
| `MEMORYLAYER_EMBED_SERVER_HOST` | `0.0.0.0` | Bind address (set `127.0.0.1` to accept local connections only) |
| `MEMORYLAYER_EMBED_SERVER_PORT` | `61051` | Listening port |
| `MEMORYLAYER_EMBED_SINGLE_VECTOR_PROVIDER` | `sentence_transformers` | `sentence_transformers` (local/CPU, 384-d), `vllm_subprocess` (GPU, 2048-d), `vllm` (in-process), `openai`, `google`, `colpali`, `mock`. **Changing this changes the vector dimension — see [Embedding dimensions](#embedding-dimensions).** |
| `MEMORYLAYER_EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Single-vector model for the active provider |
Expand Down Expand Up @@ -188,7 +197,7 @@ The Docker image's healthcheck targets `/health`.

## Versioning

This package is released in lockstep with `memorylayer-server` (currently `0.1.22`). The version pin in `dependencies` keeps client and server protocol versions aligned.
This package is versioned alongside `memorylayer-server`; the exact `memorylayer-server==<version>` pin in `dependencies` keeps client and server protocol versions aligned.

## License

Expand Down
12 changes: 6 additions & 6 deletions memorylayer-embed-server/docs/embedding-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ export MEMORYLAYER_EMBED_USE_MOCK_PROVIDERS=true
* Model load is lazy, guarded by a lock (concurrent first requests load
once, not N times), and hoisted to startup by
`MEMORYLAYER_EMBED_PRELOAD_MODELS=true` (the default).
* Requires the `[local]` extra (`pip install "memorylayer-embed-server[local]"`).
* Requires the `[local]` extra (`pip install "./memorylayer-embed-server[local]"`).
Because this is the *default* provider, a bare install with no extra is
the most likely first-run failure — the log names the exact install
command rather than raising a bare `ImportError` traceback.
Expand Down Expand Up @@ -172,7 +172,7 @@ Swapping the model changes the vector width (e.g. `all-mpnet-base-v2` is
* Multimodal: supports image embedding via the
`{"prompt": "...", "multi_modal_data": {"image": <PIL.Image>}}`
prompt shape, so models like `Qwen/Qwen3-VL-Embedding-2B` are first-class.
* Requires the `[vllm]` extra (`pip install memorylayer-embed-server[vllm]`)
* Requires the `[vllm]` extra (`pip install "./memorylayer-embed-server[vllm]"`)
and a CUDA-capable host. `Dockerfile.real-test-full` installs this.

**Env knobs**:
Expand Down Expand Up @@ -346,7 +346,7 @@ Requires installing the OSS server with the `google` extra
(`qwen2.5` → ColQwen2.5, `qwen2` → ColQwen2, `modernvbert` →
ColModernVBert, `colpali` → original ColPali). Defaults to
ColModernVBert (MIT-licensed, smallest).
* Requires the `[colpali]` extra (`pip install memorylayer-embed-server[colpali]`)
* Requires the `[colpali]` extra (`pip install "./memorylayer-embed-server[colpali]"`)
which pulls in `colpali-engine` + `torch`. GPU strongly recommended.

**Env knobs**:
Expand Down Expand Up @@ -471,7 +471,7 @@ multi-vector endpoints will 503.

### Observability

Install with `pip install memorylayer-embed-server[observability]`
Install with `pip install "./memorylayer-embed-server[observability]"`
(or `[all]`). The embed-server reuses the OSS server's pluggable
`MetricsService` and `OTelInitPlugin`.

Expand Down Expand Up @@ -568,7 +568,7 @@ config keys are documented separately.
### Local / CPU quick start (no GPU, real embeddings)

```bash
pip install "memorylayer-embed-server[local]"
pip install "./memorylayer-embed-server[local]"
memorylayer-embed serve
```

Expand All @@ -592,7 +592,7 @@ a GPU.
### Fully GPU-free, single **and** multi vector

```bash
pip install "memorylayer-embed-server[local,colpali]"
pip install "./memorylayer-embed-server[local,colpali]"
```

```
Expand Down
7 changes: 4 additions & 3 deletions memorylayer-embed-server/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ dependencies = [
[project.optional-dependencies]
# Local/CPU single-vector embeddings (sentence-transformers, all-MiniLM-L6-v2).
# This backs the DEFAULT single-vector provider, so it is what a local install
# needs: pip install "memorylayer-embed-server[local]". Kept an extra rather than
# needs: pip install "./memorylayer-embed-server[local]" from a repository
# checkout (the package is not on PyPI). Kept an extra rather than
# a base dependency because it pulls torch, and deployments that only use the
# openai/google passthrough should not pay for that.
local = ["sentence-transformers>=3.0.0", "torch>=2.11.0,<2.12.0"]
Expand All @@ -57,8 +58,8 @@ observability = [
]
gpu = ["memorylayer-embed-server[ocr,vllm,colpali]"]
all = ["memorylayer-embed-server[local,gpu,google,observability]"]
# Visual-tokenizer (Qwen3.5) lives in the proprietary
# memorylayer-embed-server-enterprise package; install that separately.
# Visual-tokenizer (Qwen3.5) lives in the AGPL-3.0 memorylayer-embed-server-enterprise
# plugin (scitrera/memorylayer-enterprise); install that separately.
dev = [
"pytest>=9.0.2",
"pytest-asyncio>=1.3.0",
Expand Down
8 changes: 4 additions & 4 deletions memorylayer-mcp-typescript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

TypeScript MCP (Model Context Protocol) server for [MemoryLayer.ai](https://memorylayer.ai).

Provides 25 memory tools by default (38 in the `full` profile) for LLM agents to store, recall, synthesize, and manage information across sessions.
Provides 28 memory tools by default (40 in the `full` profile) for LLM agents to store, recall, synthesize, and manage information across sessions.

## Installation

Expand Down Expand Up @@ -112,8 +112,8 @@ Tools are organized into profiles selected via `MEMORYLAYER_TOOL_PROFILE`:

| Profile | Count | Description |
|---------|-------|-------------|
| `cc` *(default)* | 25 | Optimized for Claude Code: core memory + sessions + context environment + chat threads + skills (read) |
| `full` | 38 | All tools: adds `associate`, `statistics`, `graph_query`, `audit`, `chat_thread_decompose`, `chat_thread_delete`, `skills_save`, and the 5 `mcp_servers_*` tools |
| `cc` *(default)* | 28 | Optimized for Claude Code: core memory + sessions (including checkpoints and context packs/deltas) + context environment + chat threads + skills (read) |
| `full` | 40 | All tools: adds `associate`, `statistics`, `graph_query`, `audit`, `chat_thread_decompose`, `chat_thread_delete`, `skills_save`, and the 5 `mcp_servers_*` tools |
| `minimal` | 2 | Just `memory_remember` and `memory_recall` |

> `memory_statistics` and `memory_audit` ship as **placeholders** in the current build; their handlers return `not_implemented` server-side.
Expand Down Expand Up @@ -403,7 +403,7 @@ The MCP server wraps the `@scitrera/memorylayer-sdk` TypeScript SDK, providing a
memorylayer-mcp-typescript/
├── src/
│ ├── types.ts # TypeScript types for MCP tools
│ ├── tools.ts # MCP tool definitions (25 in cc / 38 in full)
│ ├── tools.ts # MCP tool definitions (28 in cc / 40 in full)
│ ├── client.ts # Wrapper around @scitrera/memorylayer-sdk
│ ├── session.ts # Local session state management
│ ├── workspace.ts # Workspace ID auto-detection
Expand Down
Loading
Loading