jade-memory

Persistent knowledge base and journal for AI agents. Two MCP servers backed by a shared multilingual embedding sidecar, deployed as Docker containers.

Knowledge base stores facts, decisions, procedures, and troubleshooting notes with semantic search. Agents call store to save knowledge and recall to retrieve it. Entries are typed, tagged, and searchable across languages.

Journal is a free-form, append-only cognitive tool. Agents write thoughts, reflections, and session notes. Value is in the writing process (structuring thinking), not just retrieval. No categories or sections — semantics live in the content itself.

Both use vector embeddings (768-dim, gte-multilingual-base) for semantic search via sqlite-vec. Both are accessible remotely via MCP Streamable HTTP transport with bearer token auth. API keys are created through the web admin UI — no env vars needed.

Architecture

┌─────────────────────────────────────────────────────┐
│  Docker network (internal bridge)                   │
│                                                     │
│  jade-embeddings (Python, port 3102, internal only) │
│    Alibaba-NLP/gte-multilingual-base                │
│    768 dims, 100+ languages, ~1.2GB RAM             │
│                                                     │
│  jade-knowledge (Bun, port 3100)                    │
│    MCP Streamable HTTP at /mcp                      │
│    Bearer token auth                                │
│                                                     │
│  jade-journal (Bun, port 3101)                      │
│    MCP Streamable HTTP at /mcp                      │
│    Bearer token auth (separate key)                 │
└─────────────────────────────────────────────────────┘

The embedding sidecar is internal-only — not exposed outside the Docker network. Both MCP servers call it to generate embeddings on store/write and on search/recall.

Tools

Knowledge base (jade-knowledge)

Tool	Description	Parameters
recall	Search knowledge base	query (string), type? (enum), limit? (int, default 10)
store	Add knowledge with auto-embedding	content (string), type? (enum, default "general"), tags? (string[])
forget	Delete knowledge entry	id (int)

Knowledge types: fact, preference, decision, procedure, troubleshooting, general

Journal (jade-journal)

Tool	Description	Parameters
write	Record journal entry	content (string)
search	Semantic search journal	query (string), limit? (int, default 10)
recent	List recent entries	limit? (int, default 10)

The journal is append-only. No delete, no edit.

Context footprint

Both MCPs add approximately ~480 tokens total to the agent's context window:

• jade-knowledge: ~300 tokens (3 tools)
• jade-journal: ~180 tokens (3 tools)

For comparison, the Playwright MCP adds ~13,700 tokens.

Installation

Prerequisites

• Docker and Docker Compose
• Ports 3100 and 3101 available on the host

1. Clone and configure

git clone <repo-url> jade-memory
cd jade-memory
cp .env.example .env
# Edit .env if you need to change ports or DB paths (no API keys needed)

2. Build and start

docker compose up -d --build

First build downloads the embedding model (~1.2GB) and bakes it into the image. This takes a few minutes. Subsequent builds use the cached layer.

The embedding sidecar has a health check with a 120-second start period to allow for model loading. The knowledge and journal containers wait for it to be healthy before starting.

3. Create admin account

Visit http://<host>:3100 (knowledge) or http://<host>:3101 (journal) in your browser. On first visit you'll be prompted to create an admin account.

4. Create API keys

Log in to the web UI, go to /admin, and create API keys. These are used by MCP clients (Claude Code, OpenCode, etc.) to authenticate. Copy the key immediately — it's only shown once.

5. Verify

# Health checks (no auth required)
curl http://localhost:3100/health
curl http://localhost:3101/health

# Test MCP auth with your API key
curl -X POST http://localhost:3100/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

6. (Optional) Reverse proxy

If you want to expose the MCPs over HTTPS via traefik or another reverse proxy:

cp docker-compose.override.yml.example docker-compose.override.yml
# Edit docker-compose.override.yml with your domain names and TLS config
docker compose up -d

Connecting to agents

API keys are created through the web admin UI at /admin after logging in. Replace <API_KEY> below with a key you created there.

Claude Code

Option A: CLI (recommended)

claude mcp add --transport http jade-knowledge http://<host>:3100/mcp \
  --header "Authorization: Bearer <API_KEY>"

claude mcp add --transport http jade-journal http://<host>:3101/mcp \
  --header "Authorization: Bearer <API_KEY>"

Use --scope user to make them available across all projects, or --scope local (default) for the current project only.

Option B: JSON config

Add to ~/.claude.json (or project-level .claude/settings.json) under mcpServers:

{
  "mcpServers": {
    "jade-knowledge": {
      "type": "http",
      "url": "http://<host>:3100/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    },
    "jade-journal": {
      "type": "http",
      "url": "http://<host>:3101/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

OpenCode

Add to opencode.json in your project root:

{
  "mcp": {
    "jade-knowledge": {
      "type": "remote",
      "url": "http://<host>:3100/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    },
    "jade-journal": {
      "type": "remote",
      "url": "http://<host>:3101/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

You can use {env:KNOWLEDGE_API_KEY} instead of a literal key to reference environment variables.

Other MCP clients

Any client that supports MCP Streamable HTTP transport can connect. The servers accept:

• POST /mcp — MCP JSON-RPC messages (requires Accept: application/json, text/event-stream)
• GET /mcp — SSE stream for server-initiated messages
• DELETE /mcp — Session cleanup
• GET /health — Health check (no auth required)

Prompting the agent

For best results, instruct the agent to use the knowledge base proactively. Add something like this to your system prompt or CLAUDE.md:

You have access to a persistent knowledge base (jade-knowledge) and journal (jade-journal).

**Knowledge base**: Use `recall` when starting a task to check for relevant prior knowledge.
Use `store` when you learn something reusable — facts, decisions, troubleshooting solutions,
procedures. Tag entries with project names for cross-project retrieval.

**Journal**: Use `write` when you want to think through a problem, reflect on your approach,
or note something for your own reference. The value is in the writing process itself.

Development

Project structure

jade-memory/
├── packages/
│   ├── shared/          # Auth, embed client, DB helpers, types
│   ├── knowledge/       # Knowledge base MCP server
│   └── journal/         # Journal MCP server
├── embeddings/          # Python embedding sidecar
├── docker-compose.yml
└── .env.example

Running tests

# All tests (from repo root)
bun test

# Specific package
bun test --filter knowledge
bun test --filter journal
bun test --filter shared

Tests mock the embedding sidecar and use in-memory SQLite databases. No Docker required.

Running locally (without Docker)

# Terminal 1: Start embedding sidecar
cd embeddings
pip install -r requirements.txt
uvicorn main:app --port 3102

# Terminal 2: Start knowledge MCP
cd packages/knowledge
EMBEDDINGS_URL=http://localhost:3102 bun run src/index.ts

# Terminal 3: Start journal MCP
cd packages/journal
EMBEDDINGS_URL=http://localhost:3102 bun run src/index.ts

No API keys needed at startup. Visit http://localhost:3100 to create an admin account, then go to /admin to create API keys for MCP clients.

Resource usage

Container	RAM	CPU	Disk
jade-embeddings	~1.2 GB	Low (idle), moderate (encoding)	~2 GB (model)
jade-knowledge	~50 MB	Minimal	Grows with entries
jade-journal	~50 MB	Minimal	Grows with entries

The embedding model (gte-multilingual-base) is the main resource cost. It supports 100+ languages including English, Spanish, French, German, and Dutch. Cross-language search works — you can store in one language and recall in another.