EchoLayer

Give Claude a long-term memory.

Claude normally forgets everything the moment a session ends — every solved problem, every decision, every lesson learned starts from zero next time. EchoLayer fixes that: it quietly records what you and Claude work on, distills it into memories, and automatically reminds Claude at the start of every new session — so it picks up where you left off.

No cloud service, no subscription, no data leaving your computer.

Who this is for

• You use Claude Code (Anthropic's desktop/terminal coding agent). That's required — the automatic capture runs on Claude Code's hooks.
• You work on ongoing projects — recruiting pipelines, reports, content, code, anything — and you're tired of re-explaining context every session.

Where it works

Where	Works?	Why
Claude Code	✅ Full	Hooks capture everything, sessions open with the memory briefing, recall on demand. This is what EchoLayer is built for.
Claude Desktop app	⚠️ Recall only	Desktop can run local MCP servers, so the recall / remember / stats tools work in chat — ask "what do you remember about X?" and get real answers. But Desktop has no hooks, so nothing gets captured there: no automatic recording, no session-start briefing. It can only read memories that your Claude Code sessions created.
claude.ai in the browser	❌ No	The website can't run programs on your machine. EchoLayer is a local database + local scripts; claude.ai has no way to reach them (its connectors only talk to remote servers — and exposing your memory database to the internet would defeat the whole privacy design).

Privacy, up front: everything stays on your machine in a local database file. Memories are scrubbed of API keys and secrets before storage, and the database is excluded from git so it can never be accidentally published. Nothing is sent anywhere except the same AI calls Claude already makes.

Install (about 5 minutes)

1. Install Node.js (the free runtime EchoLayer runs on) — download the LTS installer at nodejs.org and click through it. Version 22.5 or newer. Already have it? Skip ahead.

2. Get EchoLayer. On this GitHub page click the green Code button → Download ZIP, then unzip it somewhere permanent, e.g. C:\EchoLayer (Windows) or ~/EchoLayer (Mac). (Or, if you know git: git clone https://github.com/SajithKSwami/EchoLayer.)

3. Open a terminal in that folder. Windows: open the folder in Explorer, right-click empty space → Open in Terminal. Mac: drag the folder onto the Terminal icon.

4. Run the setup:

   node setup.mjs

   This installs dependencies and registers EchoLayer's memory tools with Claude Code.

5. Turn on automatic memory for a project (the folder where you run Claude Code):

   node setup.mjs --enable-memory "C:\path\to\your\project"

   It backs up your settings before touching anything, and it's safe to run twice.

6. Restart Claude Code in that project. From now on, every new session begins with an "EchoLayer memory" briefing — lessons learned and relevant past work — and you can ask Claude things like "what do you remember about the Q3 hiring report?" at any time.

Optional: sharper recall (free)

Out of the box, recall uses a simple keyword matcher. For true meaning-based recall ("comp bands" finds your salary-benchmarking work), get a free Google AI key at aistudio.google.com/apikey, copy .env.example to .env, and paste the key in. EchoLayer detects it automatically. (Switching modes needs a fresh start — delete echolayer.db once.)

Uninstall

Delete the EchoLayer folder, run claude mcp remove echolayer, and remove the three hooks entries from your project's .claude/settings.local.json (setup made a .bak copy you can restore). Your memories live in echolayer.db — keep or delete as you wish.

What you get

• Session briefings — new sessions open with what matters: corrective lessons first, then relevant past work. Claude starts already knowing.
• Ask-anytime recall — echolayer_recall returns a compact ranked index of memories; Claude drills into full detail only for the ones it needs (cheap on tokens by design).
• Deliberate memory — tell Claude "remember that we decided X" (echolayer_remember).
• Self-improving — EchoLayer reflects on activity, synthesizes lessons from failures, merges repeated lessons instead of duplicating them, and prunes cold memories over time.
• Inspectable — node recall/timeline.mjs shows everything stored, filterable (--kind corrective, --grep hiring, --full).

---

For engineers

EchoLayer captures every tool call, pages it through a bounded working buffer, persists a date-indexed episodic stream, synthesizes reflection trees that link back to their evidence, and serves it all back through a tri-metric retrieval engine (recency · importance · relevance) with a lexical/semantic hybrid relevance term.

A synthesis of four works: CoALA (working/episodic/semantic split), Generative Agents (memory stream, reflection, recency · importance · relevance), ReAct (the {thought, action, observation} trajectory), Reflexion (corrective reflections bounded to Ω). Full design + decisions log: ARCHITECTURE.md.

Does it actually help?

Measured, not asserted. The benchmark pits EchoLayer against the two things an agent does without memory — dump all history, or dump recent history — at an equal context budget:

Strategy	Tokens / query	Relevant memory retrieved
Dump all history	399	100%
Dump recent 8	131	40%
EchoLayer recall (K=8)	140	100%

Same accuracy as full history at 65% fewer tokens, and 100% vs 40% against recency-only at the same budget. Live gemini-embedding-001, 24-episode corpus, 10 labeled queries. Reproduce: node bench/run.mjs. Scope and honest limits in bench/README.md.

Architecture

Layer	Module	Responsibility
L0	capture/	event build + secret-scrub + status classification (ok/error/denied)
L1→L2	flush/	batched rate + embed → episodes (injected llm/embedder)
L1–L3	store/	node:sqlite schema, Float32 vector codec, repository
L3	reflect/	thematic (Σ-importance) + corrective (loop/failure) reflections, dedup-at-insert
L4	retrieval/	tri-metric scorer (hybrid lexical+cosine relevance)
L4	recall/	query surface, session-start briefing, progressive disclosure, timeline CLI
—	prune/	forgetting: cold-episode pruning + retroactive reflection dedup

MCP tools: echolayer_recall (compact index), echolayer_detail (drill-down), echolayer_remember, echolayer_stats. Hooks: SessionStart (briefing injection), PostToolUse (capture), Stop (rate/embed/reflect). Raters: Claude claude-haiku-4-5 or Gemini gemini-2.5-flash; embedder gemini-embedding-001 — each with a deterministic fake fallback when no key is set (zero API cost in CI).

127 tests, zero-dependency core (node:sqlite, Node ≥ 22.5). Run: node --test. Try recall on fakes: node recall/cli.mjs "deploy error".

Manual MCP registration (what setup.mjs does):

claude mcp add echolayer --scope user -- node /path/to/EchoLayer/mcp/server.mjs

Hooks JSON for hand-wiring: node setup.mjs --print-hooks. DB path override: ECHOLAYER_DB.

License

MIT