Memex

Memex

!Memex Architecture

Personal knowledge base as a GitHub template. An MCP server gives AI agents tools to search, read, and add knowledge. Writes go through Cursor Cloud Agents — a cloud agent reads your .cursor/rules/, creates properly formatted entries with cross-references, and opens a PR for you to review.

How It Works

You: "add what we discussed about transformers to my knowledge base"
  ↓
Your AI agent summarizes the discussion
  ↓
Calls kb_add(summary) via MCP
  ↓
Cursor Cloud Agent spawns, reads .cursor/rules/,
creates atomic entries with typed edges, opens a PR
  ↓
You review and merge

Read path: MCP server reads from local disk — fast, no API calls. Write path: Cloud agent handles formatting, cross-references, and PRs.

Quick Start

1. Click Use this template on GitHub
2. Clone your new repo locally
3. Configure:

cp .env.example .env
# Edit .env — set CURSOR_API_KEY
# Edit config.yaml — set github.owner and github.repo

1. Run the server:

uv run memex

1. Add to Cursor MCP config (.cursor/mcp.json):

{
  "mcpServers": {
    "memex": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

Done. Your AI agent now has access to kb_search, kb_list, kb_read, kb_add, and kb_status tools.

Knowledge Model

Flat knowledge graph: every entry is knowledge/{slug}.md.

---
title: "RLHF"
type: concept                    # concept | reference | insight | question | note
summary: "Fine-tuning LLMs using human preference feedback"
tags: [ml, alignment]
created: "2026-02-09"
edges:
  - path: /knowledge/reward-model.md
    label: uses
    description: "Reward model scores outputs for training signal"
sources:
  - url: "https://arxiv.org/abs/2203.02155"
---

• Typed edges in frontmatter — the graph's source of truth
• Markdown links in body — for readability, clickable on GitHub
• Backlinks computed dynamically by the server
• Body templates per type (concept → Definition/How It Works/Connections, etc.)

MCP Tools

| Tool | Description | |------|-------------| | kb_search(query) | Fulltext search across entries | | kb_list(type?, tag?) | List entries with optional filters | | kb_read(path) | Read entry with edges and backlinks | | kb_add(summary) | Launch cloud agent to add knowledge via PR | | kb_status(agent_id) | Check cloud agent status and PR URL |

Viewer (GitHub Pages)

A static site with entry list, filters, and interactive graph visualization.

Deploy automatically when a PR is merged into master that changes knowledge/ (also redeploys on viewer/ changes).

Manual deploy: go to Actions → Deploy Knowledge Base Viewer → Run workflow.

The viewer reads knowledge/*.md, builds a data.json, and deploys a single-page app with vis.js graph.

Running with Docker

docker compose up

Remote Deployment

Deploy the Docker image to any host. Set these env vars:

| Variable | Purpose | |----------|---------| | MEMEX_GIT_URL | Repo URL for cloning | | MEMEX_GIT_TOKEN | GitHub PAT for private repos | | MEMEX_AUTH_TOKEN | Bearer token for MCP endpoint auth | | CURSOR_API_KEY | For kb_add (Cloud Agents API) | | OPENAI_API_KEY | For semantic search (optional) |

Cursor MCP config for remote:

{
  "mcpServers": {
    "memex": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Search Backends

Configured in config.yaml under search.backend:

• bm25 (default) — term-frequency relevance ranking via rank-bm25
• substring — zero-dependency fallback, case-insensitive match
• semantic — OpenAI embeddings with cosine similarity (requires OPENAI_API_KEY)

CLI

The cloud agent uses CLI tools to query the KB during PR creation:

uv run python -m server.cli search "reinforcement learning"
uv run python -m server.cli list --type concept --tag ml
uv run python -m server.cli read /knowledge/rlhf.md
uv run python -m server.cli stats