memeX
Apache 2.0Cognitive memory for AI agents
Your AI has amnesia.
memeX fixes it.
The missing memory layer for Claude Code, Cursor, Windsurf, Cline, and every LLM agent.
One install. Every editor. Free. Forever.
PyPI · Docker · Apache 2.0 · OMP v0.1 reference impl
Works with every AI editor
Claude Code
MCP · 9 hooks
memex init (auto-wires hooks + MCP)
Cursor
MCP + rules
memex init (auto-wires MCP + drops rules file)
Windsurf
MCP + rules
memex init (auto-wires MCP + rules)
Cline
MCP · VS Code
memex init (auto-wires MCP + rules)
Aider
HTTP
Talk to localhost:7777
Any HTTP client
HTTP / REST
curl http://127.0.0.1:7777/recall
Install in three commands
pipx-based, runs locally, no cloud, no telemetry. Same wheel for Mac, Windows, Linux.
macOS
brew install python@3.12 pipx
pipx ensurepath
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl
memex initWindows
winget install Python.Python.3.12
winget install Microsoft.VCRedist.2015+.x64
python -m pip install --user pipx
python -m pipx ensurepath
# close + reopen PowerShell
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl
memex initLinux
sudo apt install python3 python3-pip pipx
# or: sudo dnf install python3 python3-pip pipx
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl
memex initDetect AI editors
Wires hooks into Claude Code, Cursor, Windsurf, Cline. All 9 Claude Code lifecycle events captured.
Always-on service
launchd (macOS) / Task Scheduler (Windows) / systemd-user (Linux) so memex starts on login.
Seed from a repo
Optional: scan a git repo and extract decisions from commit history, ADRs, README, manifests.
Then open the UI:
http://127.0.0.1:7777Windows requires the VC++ Redistributable (winget line above installs it). See INSTALL.md for troubleshooting.
The memex web UI · live screenshots from the running daemon
same_as links.
Repo-aware. Microservice-aware.
Memory that crosses repository boundaries.
Real codebases are split across repos. memex ingests every one of them and surfaces decisions made in auth-service when you're working in billing-service. No more re-explaining context per repo.
tree-sitter chunkers
Per-language AST chunking for Python, Go, JS/TS, Java, Bash, YAML, HCL, Svelte, and more. Functions, classes, structs, endpoints become typed nodes — not raw text blobs.
cross-repo edges
When the same module / endpoint / decision shows up across repos, memex links them. Recall in repo B traverses to relevant nodes in repo A — no extra prompting needed.
memory neighborhood
Each source file gets a memory neighborhood: the concepts, decisions, and constraints that ever touched it. Open a file, see its history. Microservice context comes for free.
Why this matters for microservices
A 10-microservice org is 10 cold sessions. memex is one shared memory across all of them — the auth contract negotiated in auth-service is the same fact when read from orders-service. Decisions don't get re-litigated, constraints don't get violated by accident, and the AI working in service N already knows what was decided in services 1..N-1.
Open protocol
memeX is the v0.1 reference implementation of MMP.
The Memory Mesh Protocol is the open spec for AI memory. Five verbs, latency contracts, provenance schema, federation — released by Quefly Enterprises LLP under CC BY 4.0. Anyone can implement it; nobody can fence it.
Apache 2.0
Code: memex
Apache 2.0 with explicit patent grant. The standard for protocol-bearing OSS — same license as Kubernetes, TensorFlow, most CNCF projects.
CC BY 4.0
Spec: MMP
Creative Commons Attribution 4.0 — the same license W3C and IETF use for protocol specs. Reproduce it, translate it, embed it in standards work; just attribute Quefly Enterprises LLP.
memex replaces
CLAUDE.md
Auto-loads every turn. Costs tokens whether relevant or not.
.cursorrules
Same problem. Doesn't sync with Claude Code or Windsurf.
Scratchpads
Chat history that gets purged when the session ends.
"You are a senior…"
Prompt prefixes that paper over missing project memory.
Fragmented chat
Three editors open, three memories, zero shared context.
Hand-tuned RAG
Single store, single retrieval, no provenance, no decay.
One persistent memory that every editor reads from. Provenance-stamped, time-decayed, retrievable on demand. The agent stops re-discovering what it already knew.
Everything in one daemon
Cognitive architecture
Multi-store: episodic / semantic / procedural. Provenance on every node, falsifiable claims, time-decay, working set. Modeled jointly on RAM hardware and human memory.
Hybrid retrieval
BM25 + vector cosine + Reciprocal Rank Fusion (k=60). Token-bounded subgraphs. p50 ~715ms · 5 concurrent in 3.5s wall-clock via ONNX session pool. Optional cross-encoder rerank for precision queries (--rerank, ~5-8s).
Skills with validation
Installable bundles (using-memex, core-validations, python-stdlib). validate("approach") returns structured checks the AI must self-attest before generating sensitive code.
MCP gateway
One MCP connection. Native memory tools + every upstream MCP server you wire in (filesystem, git, github, slack, postgres, k8s, sentry — 18 in catalog). Auto-observes every call.
Repo + code awareness
tree-sitter chunkers for 10 languages. Source files become nodes with cross-repo edges. Decisions made in repo A surface when working in repo B.
Tasks & projects
First-class task model with priority, status, owner, due date, project. Every task is a typed node — link decisions to the work they shipped in. Comment threads live on the same graph as the rest of your memory.
Rules & AFK mode
Experimental: define rules the AI must obey ("never run destructive ops in prod", "always validate before subprocess"). AFK mode runs long autonomous sessions with a tighter rule set + audit trail you can review on return.
Local-first, runs anywhere
Apache 2.0, no cloud, no telemetry. ~440KB wheel + onnxruntime + fastembed pull on install. Web UI, CLI, MCP stdio, HTTP — all from one daemon at localhost:7777.
Three frontends, one engine
MCP stdio for AI editors. HTTP for everything else (Aider, JetBrains, custom agents, scripts). CLI for shells. All read/write the same on-disk graph.
Self-hosted by default
No cloud, no telemetry, no API keys, no rate limits. Per-machine auth token (mode 0600). Apache 2.0 licensed.
Zero-friction setup
`memex init` runs a 3-step wizard: detect Claude Code / Cursor / Windsurf / Cline + wire them, install the always-on service (launchd / Task Scheduler / systemd), optionally seed from a git repo. Atomic edits — your other config is untouched.
Skill catalogue
Validation bundles, ready to install.
Skills give a fresh memex install immediate value — and force the AI to self-attest checks before generating sensitive code. Three builtins ship with every install. Custom and community skills load from local paths or the planned queflyhq/memex-skills registry.
using-memex Bootstrap meta-skillTeaches any AI tool how to use memex itself — when to recall, when to validate, when to observe, when to add. Every install ships with this.
core-validations Globally-applicable principlesLanguage-agnostic approaches: secure-subprocess, money-decimal-precision, structured-concurrency-async, crypto-secrets-not-random, user-input-untrusted-by-default, sql-parameterized-queries, error-handling-fail-loud, logging-structured-and-no-secrets.
python-stdlib Python-specific gotchasIdioms and version-specific behaviors in datetime, asyncio, subprocess, logging, decimal, secrets, functools, contextlib, argparse, pathlib, tempfile, concurrent.futures.
Author your own.
A skill is just manifest.json + concepts.jsonl in a folder, or a single *.memex.jsonl file in your repo. Drop knowledge in your codebase; memex bootstrap auto-installs it.
Under the hood
A single Python daemon. One DuckDB file. Three frontends. Here is what's actually inside.
1 · The engine — protocol-blind, single-file storage
memex.duckdb in your data dir holds concepts, edges, episodic events, and embeddings — one file, single-writer multi-reader. Every node carries source, created_at, last_confirmed_at, and confidence. The schema rejects anything missing them.
2 · Working set + decay — RAM and human memory
A bounded LRU WorkingSet biases recently-touched concepts higher in retrieval ranking — modeled on CPU L1 cache and human working memory. Confidence decays on an Ebbinghaus exponential (default 90-day half-life) unless re-confirmed. Stale memory is worse than no memory.
3 · Hooks & auto-capture
Optional Claude Code hooks emit a SessionStart preamble of relevant memory and auto-detect user corrections (user_correction events). Every add / recall / validate / call_upstream auto-emits an episodic event for later consolidation.
4 · Auth model
On first daemon start, memex generates a per-machine bearer token at <data_dir>/daemon.token (mode 0o600 on POSIX). The CLI read it automatically. Binding to a non-loopback address requires MEMEX_AUTH_TOKEN — fail loud, never silent.
5 · Built in
Install in 60 seconds
# Install (any platform)
pipx install memex
# Auto-detect and wire every AI editor at once
memex setup
# Bootstrap with the meta-skills
memex install skill:using-memex
memex install skill:core-validationsMore install options on the download page.
Open for contribution
Build memex with us.
Apache 2.0 licensed. Issues and PRs welcome. The architecture is Protocol-based, so dropping in a new retrieval strategy or store backend is a single file. Code of Conduct: Contributor Covenant. We respond in days, not months.
File an issue
Bugs · feature requests
Bug template asks for the memex doctor output and minimal repro. Feature template asks for the underlying friction first.
Send a PR
Code · docs · skills
A skill bundle is two files. A new retrieval strategy is one Protocol implementation. Frontend, store, embedder — same shape: implement the Protocol, drop it in.
Read the guide
CONTRIBUTING.md
Dev setup, where to add things (skills, retrieval, stores, frontends), architectural rules, the SOLID-with-Protocols philosophy, and the merge bar.
Roadmap
GA
Foundations + skills + MCP gateway + curated upstream catalog. Local-first, Apache 2.0, zero telemetry. OMP v0.1 reference impl.
Consolidation + perception
Episodic→semantic promotion via memex consolidate; active pruning of stale nodes; per-tool MCP registration.
Self-curation
Background consolidation, decay, dedup, contradiction detection.
Code-verified confidence
Memory grounded in actual code state — falsifiability checked by background pass.
Team mode + AuthFI
memex daemon deployed on a team server; AuthFI handles SSO + member identity; every node carries actor=<authfi_user_id>.
Open source · Apache 2.0 · v1.0 GA · MMP reference impl
Ship better, with a memory that doesn't forget.
Free for every developer, forever. Talk to us when your team is ready for shared, self-hosted memory.