jev-memory-selector

Filters memories an agent already retrieved, so only what fits the budget is sent.

Author: Pinuts. MIT license.

Stack: Python 3.10+, HTTP, MCP stdio, Docker, HTML demo.

After jev-memory serve: demo

Local, no keys

git clone https://github.com/Pinutss/jev-memory-selector
cd jev-memory-selector
uv sync
uv run jev-memory demo
uv run jev-memory serve

No agent and no LLM are required. JEV_PROVIDER=auto (the default) stays on the local heuristic. If JEV and a gateway are configured, they are used as the judge. Docker:

docker compose up

Cursor and Hermes plugin

This repository is an Agent Plugin. Cursor and Hermes can install it directly.

Hermes

hermes plugins install Pinutss/jev-memory-selector --enable

Cursor

Install from the JEV plugins marketplace, or copy this folder to ~/.cursor/plugins/local/jev-memory-selector.

One tool: memory_select. Pass query + memories. Keys stay in the process environment, not in the call.

Requires uv. JEV_PROVIDER defaults to local.

Hermes and OpenClaw

Yes, locally. The MCP process does not need JEV or a gateway:

uv run jev-memory mcp

One tool: memory_select. Pass query + memories. Keys stay in the process environment, not in the call.

Hermes (~/.hermes/config.yaml):

mcp_servers:
  jev-memory:
    command: uv
    args: ["run", "--directory", "/path/to/jev-memory-selector", "jev-memory", "mcp"]
    env:
      JEV_PROVIDER: local

Then hermes mcp test jev-memory and /reload-mcp.

OpenClaw (~/.openclaw/openclaw.json, or Settings > MCP > Stdio):

{
  "mcp": {
    "servers": {
      "jev-memory": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/jev-memory-selector", "jev-memory", "mcp"],
        "env": { "JEV_PROVIDER": "local" }
      }
    }
  }
}

Python

from jev_memory_selector import MemorySelector

result = MemorySelector(provider="local").select(
    query="How does my backend work?",
    memories=[{"id": "1", "content": "Backend FastAPI"}],
    max_memories=8,
    max_tokens=3000,
)
print(result.texts)

JEV + gateway (optional)

If you wire the cloud later, two keys are enough: JEV_API_KEY / JEV_BASE_URL, and your gateway (GATEWAY_API_KEY, GATEWAY_BASE_URL, GATEWAY_MODEL). No OpenAI / Anthropic / Gemini key in this repo.

If you have several LLMs or a multi-model key (OpenRouter, Groq), pick the judge model with jev-model-router, then set GATEWAY_* to that endpoint. Keys stay in the environment, never in the request body.

cp .env.example .env

JEV_PROVIDER=jev will not start if either side is missing. With auto, missing keys just keep the local heuristic.

HTTP

uv run jev-memory serve

GET /healthz, POST /v1/select. Binds 127.0.0.1. The body must not contain keys.

Limits

The default counter is about 4 characters per token. In local mode, ranking is lexical. Scope isolates lists, it is not auth. No store, no PyPI yet.

docs/vision.md is a long-term target, not the current contract.