Permanent, cross-session memory for AI coding assistants.
Every AI coding tool forgets everything when a new session starts. The AI Experience Layer doesn't. It stores your project's full journey — what you tried, why it failed, what worked, and the lesson — then injects it back into your AI at the exact moment it's needed, in every future session.
Website: AI Experience Layer (served via GitHub Pages) · Product code: ai-experience-layer/
- What this is
- Why it exists
- Quick start
- Benchmarks
- Features
- MCP tools (12)
- CLI
- How it works
- Repository layout
- Cost
- Privacy
- Development & testing
- FAQ
- Roadmap
- License
The AI Experience Layer (AEL) is a memory engine for AI coding assistants. It sits between your AI (OpenCode, Claude Code, Cursor, Freebuff, Codex, Gemini CLI, …) and a local PostgreSQL database, and gives your AI three things it normally doesn't have:
- Rules — permanent guidelines that load at the start of every session ("always use Gemini 3.1 Flash, never 1.5 Flash")
- Decisions — past choices with reasoning and rejected alternatives ("chose PostgreSQL over SQLite because …")
- Experiences — full problem-solving journeys: task → attempts → why each failed → what worked → the reusable lesson
It works two ways:
- As an MCP server — your AI gets 12 native callable tools and uses them automatically during real work
- As a terminal CLI (
ael) — any AI that can run a bash command can store and retrieve knowledge, no MCP support needed
Everything runs locally, first. Embeddings are computed on your machine. The only paid step is an optional ~$0.001 LLM call that converts a plain-English description into a structured lesson.
Ask any developer who uses AI coding tools: "How many times has your AI repeated a mistake you already fixed?"
The answer is always the same — constantly. Every new session starts from zero:
- Your AI hits the same error it solved last week
- Your AI re-proposes an approach you already rejected — with reasons
- Your AI forgets the rules you spent a session establishing
- Your team's AI forgets architecture decisions made three weeks ago
The AI Experience Layer is the memory that survives between sessions. It's the difference between re-debugging for 40 minutes and solving it in 5 — because your AI remembers that it already solved this.
git clone https://github.com/AbhayXplor/Experience.git
cd Experience/ai-experience-layer
npm run setupOr use the platform launcher: ./setup.sh (macOS/Linux) or setup.cmd (Windows).
That single command:
- Checks Node.js (18+ required)
- Creates
.envfrom the template (never overwrites an existing one) - Installs dependencies
- Builds the server
- Starts PostgreSQL via Docker automatically (if not already running)
- Creates the database tables + pgvector extension
- Verifies everything with
doctor
Safe to re-run at any time — it never deletes or overwrites your data.
# Try the demo (seeds sample data and shows how it works)
node dist/cli.js demo
# Add your OpenRouter API key to .env (required only for AI extraction)
# OPENROUTER_API_KEY=sk-or-...
# Connect your AI assistant (OpenCode, Claude Code, Cursor, etc.):
# Tell your AI: "Read SETUP.md and configure the Experience Layer for me."No MCP support in your CLI? Every AI with terminal access can still use it:
ael submit my-project "what happened, what I tried, what worked"
ael retrieve my-project "what I'm about to do"The AI Experience Layer is measured on CodeMemEval — a benchmark we built because existing ones (LongMemEval, LOCOMO) measure chat memory, not coding memory. CodeMemEval is 502 queries across 136 real engineering experiences in 5 projects, 11 categories, every answer machine-checked — no LLM judges, identical results every run.
| Category | What it tests | n | Recall@5 | MRR |
|---|---|---|---|---|
error_fix |
"This exact error again" finds the past fix | 108 | 100% | 99.5% |
journey_recall |
Vague symptom finds the whole journey | 43 | 97.7% | 79.4% |
rejected_approach |
"Should we do X?" finds where X already failed | 150 | 85.3% | 77.9% |
paraphrase |
Zero shared keywords — pure meaning search | 68 | 85.3% | 65.4% |
knowledge_update |
New fix outranks the outdated one it replaced | 10 | 100% | 95.0% |
decision_recall |
Past decisions with reasoning | 15 | 100% | 96.7% |
rule_recall |
Permanent project guidelines | 5 | 100% | 100% |
cross_project_transfer |
A lesson from Project A helps Project B | 8 | 100% | 91.7% |
cross_project_isolation |
No leakage between unrelated projects | 6 | 100% | 100% |
pattern_detection |
Recurring errors / success rates surfaced | 5 | 100% pass | — |
dedup |
Duplicates rejected — no double storage | 84 | 100% pass | — |
Overall: R@5 90.4% · MRR 86.5%
Run it yourself — the harness and dataset ship in the repo:
cd ai-experience-layer
npx tsx benchmark/codememeval-bench.ts # ~5 min, free, identical numbersLongMemEval-S (UCLA, ICLR 2025) is a chat-memory benchmark — not our native domain. We run it anyway because our closest open-source competitor published on it, and a fair fight beats a cherry-picked one. Same benchmark, same embedding model (all-MiniLM-L6-v2), machine-checkable:
| Metric | Experience Layer | vs AgentMemory (published) |
|---|---|---|
| Recall@5 | 94.2% | 95.2% (within 1.0 pt) |
| Recall@10 | 96.2% | ~98% |
| Recall@20 | 98.6% | ~99% |
| NDCG@10 | 84.4% | ~88% |
| MRR | 84.7% | 88.2% (within 3.5 pts) |
Key properties of both benchmarks:
- 100% reproducible — deterministic, non-LLM, zero cost. Anyone can rerun them and get the same numbers.
- No LLM judges — every question has a known-correct answer. We check: did the right memory land in the top 5?
- Coding memory is our turf — CodeMemEval covers error→fix recall, rejected approaches, supersession, cross-project transfer; the categories competitors don't even measure.
| Layer | What it stores | Example |
|---|---|---|
| Rules | Permanent guidelines | "Always use Gemini 3.1 Flash, never 1.5 Flash" |
| Decisions | Choices with reasoning | "Chose PostgreSQL over SQLite because…" |
| Experiences | Full problem-solving journeys | "Fixed Docker port conflict → tried X → failed → tried Y → worked → lesson: check ports first" |
| Feature | What it does |
|---|---|
| Full journeys, not facts | Stores the entire arc — task → attempts → errors → principle — so the why survives |
| Semantic search (×3 weight) | Finds relevant experiences even in completely different words |
| Multi-signal retrieval | 6 signals fused with weighted RRF: structural, error-match, task-type, metadata, lexical, semantic |
| Adaptive cross-encoder reranking | Re-orders candidates only when the set is large or near-tied — free when it doesn't help |
| Supersession | New knowledge that contradicts old automatically marks the old as superseded |
| Cross-project knowledge | A Docker fix from Project A helps Project B — with isolation, so unrelated projects never leak |
| Pattern detection | Spots recurring errors, problematic files, and success rates across experiences |
| Privacy redaction | Strips API keys and passwords before anything is stored |
| MD5 deduplication | Identical submissions rejected — no double-storage |
| Tiered context assembly | Retrieval labeled Critical / Relevant / Background so the AI uses context budget wisely |
| Smart reminders | Every tool response reminds the AI to retrieve before tasks, submit after — because AIs forget mid-deep-work |
Works as an MCP server (OpenCode, Claude Code, Cursor, Windsurf, Cline, Roo, Gemini CLI, Continue, Codex, Freebuff, and more) and as a plain terminal CLI for any AI that has a shell.
Most developers don't use a "memory layer" at all — they use markdown files (AGENTS.md / CLAUDE.md), notes apps (Obsidian), or nothing and just accept that their AI forgets. The dedicated tools (Mem0, AgentMemory) exist but were built for different problems. Here's the honest comparison.
| Approach | What it is | Why it falls short for coding memory |
|---|---|---|
| AGENTS.md / CLAUDE.md | A static markdown file of rules/context that your AI loads at session start | Static text an AI may read once. It goes stale — nothing updates it. A 2026 study found hand-maintained memory files rot, and LLM-auto-generated memory files actively hurt task success by 0.5–3% and raised costs ~20% by adding noise. No search, no supersession, no cross-project. |
| Obsidian | A manual markdown knowledge vault (notes, links, graph view) | You maintain it by hand. Zero AI integration, zero retrieval for agents, zero awareness of what happened in your coding sessions. |
| Built-in context / fresh session | Your AI's context window | Resets every session. Nothing persists — the exact problem this project solves. |
| Mem0 | General-purpose agent memory (vector + graph) | Built for any domain — extracted atomic facts, not coding journeys. LLM-judged scores (not reproducible). Knowledge-update is a documented weak spot (~60s on its own benchmark family). Paid cloud tiers ($19–249/mo); self-hosting is manual. |
| AgentMemory | Open-source memory server for coding agents (MCP + hooks) | Excellent auto-capture via lifecycle hooks and a session-replay viewer — but it captures events, not structured lessons (task → attempts → why failed → what worked). No 3-layer model (rules/decisions/experiences), no cross-project isolation, no pattern detection, no coding benchmark. Chat-memory benchmark only. |
| AI Experience Layer (us) | Coding-memory engine: MCP server + terminal CLI + web dashboard | See the feature matrix below. |
| Capability | AEL (us) | AGENTS.md | Obsidian | Mem0 | AgentMemory |
|---|---|---|---|---|---|
| Full problem→solution journeys (structured lessons) | ✅ | ❌ | ❌ | ||
| Rules + Decisions + Experiences (3 knowledge layers) | ✅ | ❌ | ❌ | ❌ | |
| Semantic search (meaning, not keywords) | ✅ | ❌ | ❌ | ✅ | ✅ |
| Supersession (outdated knowledge auto-marked) | ✅ | ❌ | ❌ | ||
| Cross-project transfer with isolation | ✅ | ❌ | ❌ | ❌ | ❌ |
| Pattern detection (recurring errors / engineering intel) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Privacy redaction (keys/passwords stripped) | ✅ | ❌ | ❌ | ||
| Reproducible coding benchmark (no LLM judges) | ✅ CodeMemEval | ❌ | ❌ | ❌ LLM-judged | ❌ chat-only |
| Works with any AI (MCP and terminal CLI) | ✅ | ✅ | ❌ | ✅ | |
| Auto-capture (memory writes itself) | 🟡 nudge; harness planned | ❌ | ❌ | ❌ | ✅ hooks |
| Local-first, free, private | ✅ | ✅ | ✅ | ✅ | |
| Cost per coding session | ~$0.001 | $0 (but costs you time) | $0 (manual) | $19–249/mo SaaS | $0 |
- AGENTS.md solves rules, not memory — and static files rot.
- Obsidian is a notes app, not an agent memory — it never sees your sessions.
- Mem0 is general memory for any agent — not built for the journey structure coding needs, and its scores aren't reproducible.
- AgentMemory has the best capture story, but stores events, not lessons — and doesn't measure itself on coding.
- We store full journeys, keep old knowledge honest (supersession), share lessons across projects safely, detect patterns, redact secrets, and prove it on a benchmark anyone can rerun.
| Tool | Priority | Description |
|---|---|---|
get_help |
🔴 CRITICAL | Start here — returns workflow instructions + auto-loaded experiences |
trajectory_submit |
🔴 CRITICAL | Store an experience after solving a problem |
trajectory_retrieve |
🔴 CRITICAL | Retrieve relevant experiences before coding |
project_init |
🔴 CRITICAL | Initialize a project |
project_insights |
🟢 OPTIONAL | Engineering intelligence — patterns, recurring errors, tech clusters |
rule_add |
🟢 OPTIONAL | Add a permanent project rule |
rule_list |
🔵 INFO | List all rules |
rule_delete |
🟢 OPTIONAL | Delete an outdated rule |
decision_submit |
🟡 IMPORTANT | Record a decision with reasoning |
decision_retrieve |
🟡 IMPORTANT | Find past decisions |
trajectory_list |
🔵 INFO | List all experiences |
trajectory_delete |
🟢 OPTIONAL | Delete an outdated experience |
| Command | Description |
|---|---|
ai-experience-layer / ael |
Start the MCP server (for AI assistants) |
ael demo |
Seed sample data and show how it works |
ael doctor |
Check if everything is configured correctly |
ael setup |
Interactive setup wizard |
ael submit <project> <text> |
Store an experience from the terminal |
ael retrieve <project> <query> |
Retrieve relevant experiences from the terminal |
ael list <project> |
List stored experiences |
ael search <project> <query> |
Full-text search |
ael replay <id> |
Replay a stored journey |
ael import <file> |
Import experiences from a file |
ael version |
Show version |
AI Coding CLI (OpenCode, Claude Code, Cursor, …)
│
│ MCP (stdio) or terminal CLI
▼
┌──────────────────────────────────────┐
│ MCP Server (12 tools) │
│ get_help, submit, retrieve, … │
└───────────────┬──────────────────────┘
▼
┌──────────────────────────────────────┐
│ Engine │
│ Extraction (LLM → structured) │
│ Retrieval (6-signal RRF fusion) │
│ Context (tiered assembly) │
│ Intelligence (patterns, supersession)│
└───────────────┬──────────────────────┘
▼
┌──────────────────────────────────────┐
│ PostgreSQL 16 + pgvector │
│ 8 tables · HNSW vector index │
│ Local embeddings (384-dim) │
└──────────────────────────────────────┘
| Table | Purpose |
|---|---|
rules |
Permanent project guidelines |
decisions |
Choices with reasoning |
trajectories |
Full problem-solving journeys |
trajectory_files |
Files involved in each experience |
trajectory_attempts |
Individual attempts (success/failure) |
trajectory_relationships |
Links between related experiences |
trajectory_errors |
Error messages from experiences |
global_experiences |
Cross-project knowledge sharing |
Multi-signal retrieval combined with weighted RRF fusion — semantic similarity counts ×3, so meaning beats keyword overlap:
- Structural — file overlap with current context
- Error matching — exact error message matching
- Task type — matching by category
- Metadata — technologies/concepts overlap (requires ≥2 distinct matching terms)
- Lexical — keyword matching via PostgreSQL full-text search
- Semantic (×3 weight) — vector similarity via pgvector — the strongest signal
An adaptive cross-encoder reranker re-orders the top candidates when the set is large (≥5) or results are near-tied — and steps aside on small clean libraries where research shows rerankers are dead weight.
Memory-Layer/
├── index.html # Official website (GitHub Pages)
├── README.md # This file
├── LICENSE # MIT
├── .gitignore # Excludes local junk from the public repo
├── .gitattributes # Line-ending normalization
└── ai-experience-layer/ # ← The product
├── README.md # Product README (full detail)
├── SETUP.md # Setup guide with exact MCP configs for every CLI
├── INSTALL_FOR_AGENTS.md # Quick-start for AI agents
├── skill.md # Usage guide your AI reads once connected
├── skills/ # Deep-dive skill docs (recall, remember, insights)
├── .env.example # Environment template
├── package.json # npm scripts (setup, build, test, ui, demo, doctor)
├── tsconfig.json
├── setup.sh / setup.cmd # One-command platform launchers
├── start-mcp.sh / start-mcp.cmd # Universal MCP wrapper (robust for every CLI)
├── src/
│ ├── index.ts # Entry point (MCP server)
│ ├── mcp-server.ts # Server + 12 tool registrations
│ ├── cli.ts + cli/ # Terminal CLI (submit, retrieve, list, search…)
│ ├── engine/ # Retrieval, extraction, context, patterns, cross-project
│ ├── storage/database.ts # PostgreSQL schema + pool
│ ├── tools/ # One file per MCP tool
│ └── ui-server.ts # Web dashboard
├── scripts/ # Setup + verification + stress test scripts
├── benchmark/ # CodeMemEval + LongMemEval harnesses (public, reproducible)
│ └── data/ # Benchmark datasets + results
└── public/ # Web dashboard UI
| Operation | Cost |
|---|---|
| LLM extraction | ~$0.001 per experience |
| Embedding generation | Free (runs locally) |
| Database operations | Free (runs locally) |
| Per coding session | ~$0.001 |
- Embeddings are computed locally — no data leaves your machine for search
- The only external call is LLM extraction (OpenRouter), which you can disable
- API keys and passwords are redacted before storage
- Everything runs on your own PostgreSQL instance
cd ai-experience-layer
npm install # install dependencies
npm run typecheck # type check
npm run build # build
npm test # 146 unit tests (vitest)
# Pipeline verification (real DB, varied data, ~16 query styles)
npx tsx scripts/pipeline-verification-test.ts
# Integrity + stress (128 experiences, 14 sections: storage, retrieval at scale,
# dedup, supersession, updates, relationships, deletion FK edge cases, patterns,
# cross-project, edge cases, persistence, 25-parallel concurrency) — non-LLM
npx tsx scripts/integrity-stress-test.ts
# Full-journey round-trip (proves stored text is never truncated) — LLM
npx tsx scripts/full-journey-roundtrip-test.ts
# LLM end-to-end (real extraction across difficulty levels) — LLM
npx tsx scripts/llm-e2e-test.ts
# CodeMemEval benchmark (reproducible, non-LLM, ~5 min)
npx tsx benchmark/codememeval-bench.ts
# LongMemEval benchmark (comparison against the chat-memory standard)
npx tsx benchmark/longmemeval-bench.tsWhy do I need this? My AI already has context. Start a new chat with your AI tomorrow and it remembers nothing — no context, no decisions, no lessons. The Experience Layer is the memory that survives between sessions: it stores what you learned, and injects it back at the start of every new chat.
Is this the same as a memory/context file? A markdown file is static text an AI may or may not read. This is a searchable, structured knowledge engine: semantic retrieval, per-project organization, cross-project sharing, contradiction detection, pattern spotting, and confidence scoring.
How is this different from Mem0 or other memory tools? Mem0 is general-purpose memory for any agent. We're built specifically for coding assistants: full problem→attempts→solution→lesson journeys (not just facts), per-project organization with cross-project transfer, supersession (old lessons auto-outdated), pattern detection, and privacy filtering. And we publish reproducible retrieval numbers on our own coding benchmark — not LLM-judged marketing scores.
Does it need the cloud? An API key? Everything runs locally — database, embeddings, search. The only paid step is a cheap LLM call (~$0.001) that converts your description into a structured lesson.
Will the AI actually call it during real work? We engineered for this: strong tool descriptions, a response footer on every tool call reminding the AI to retrieve before each sub-task and submit after each problem, auto-injected context at session start, and rules injection (AGENTS.md / CLAUDE.md) for CLIs that support it.
Can teams share knowledge? Yes. Knowledge is organized per project, and multiple people on the same project share the same store. Cross-project sharing means a solution in one project can help another, automatically.
Is my data private? Yes. It lives in your local PostgreSQL database. API keys and passwords are stripped before storage. Nothing leaves your machine except the optional LLM extraction call.
- Harness (planned) — a CLI with guaranteed capture: memory that writes itself from session events, with zero AI tool-calls required
- Cloud / team tier (planned) — managed hosting, shared team memory, sync across machines
- More CLIs — deeper native integrations beyond MCP + terminal
- Better embedding model — stronger semantic models once thresholds are recalibrated
MIT — free for personal and commercial use.