memorised-them-all 2.3.0

Local, token-free file digestion → knowledge-graph memory for Claude. Convert any attachment to Markdown and digest it into a graph + exportable memory, entirely on-device. Tuned for Apple silicon.

Memorised them All

Give Claude a private memory of your files — without paying for it in tokens.

Point it at a folder of PDFs, Word/Excel files, or whole archives. It reads and remembers them entirely on your own computer — no AI models to install, no copy-pasting, no uploads, no API keys, no surprise token bills. Just ask Claude about them later.

What is this? · Get started · First memory · Use cases · FAQ · Advanced

---

🧠 What is this?

Imagine you could hand Claude a filing cabinet of your documents and say "remember all of this." Later you just ask questions, and Claude answers from what it remembers — citing which document each fact came from.

That's Memorised them All. It's a small add-on (an MCP server) for Claude Desktop and Claude Code that:

1. Reads your files — PDFs, Word/Excel/PowerPoint, web pages, CSVs, even zip/rar archives (unpacked safely) — and converts them to clean text on your computer.
2. Builds a memory — a searchable map of the people, topics, and facts inside them (a "knowledge graph"), plus a tidy summary and per-document notes.
3. Lets you ask — Claude recalls just the relevant bits when you ask, instead of you pasting whole files into the chat.

The one-line idea: Claude tokens cost money; your computer's effort is free. So all the heavy lifting happens locally, and Claude only ever receives a tiny answer. Memorising a 500-page folder costs roughly zero chat tokens.

💬 See it in action

Once it's installed, you just talk to Claude normally:

You:    Memorise everything in ~/Documents/contracts.
Claude: ✅ Digested 38 files → 421 facts across 7 themes. (took ~30s, all local)

You:    Which contracts mention an auto-renewal clause, and when do they renew?
Claude: Three do — the Globex MSA (renews 1 Jan, 60-day notice), … [cites each source]

You:    What changed between the 2023 and 2024 progress reports?
Claude: Three headline shifts — … [cites each source document]

Nothing left your machine. Claude never saw the 38 files — only the small answers.

---

🚀 Get started in about a minute

You need Python 3.10 or newer (most Macs and Linux PCs already have it; Windows users can install it from python.org — tick "Add to PATH"). Everything else installs automatically the first time you use it.

Pick whichever matches how you use Claude:

▶ Claude Desktop (easiest — no terminal)

1. Download memorised-them-all.mcpb from the latest release.
2. Double-click it. Claude Desktop opens and offers to install the extension — click Install.
3. Done. Start a chat and say "Memorise my Documents folder."

▶ Claude Code

claude
# then, inside Claude Code:
/plugin marketplace add GRU-953/memorised-them-all
/plugin install memorised-them-all

▶ Any other setup (pip)

pip install memorised-them-all

Then register it with Claude — easiest is to let it configure itself:

mta setup-claude     # writes the MCP server into Claude Desktop (and Claude Code) config

(The install.sh installer runs this for you automatically.) Or add it by hand — it just runs mta serve:

{
  "mcpServers": {
    "memorised-them-all": { "command": "mta", "args": ["serve"] }
  }
}

💡 Prefer Homebrew or Docker? brew install GRU-953/memorised-them-all/mta, or see Run it in Docker. All paths give you the same thing.

Do I need to install AI models?

No — it works the moment it's installed. Out of the box it uses fast, built-in techniques (no downloads, fully offline).

There are no AI models to install — the engine is deterministic (plain rules + maths), so it works the same on every computer, every time. To check your setup, run:

mta doctor

---

📁 Your first memory

1. Tell Claude what to remember — point it at a folder, a file, or a pattern:

   "Memorise everything in ~/Documents/research."

   (Behind the scenes Claude calls the digest tool. The first run may take a little longer while it sets things up.)

2. Ask away — in plain language:

   "What do my documents say about the Q3 budget?" "Summarise everything about Project Apollo." "Who is mentioned most often, and in which files?"

3. Explore visually (optional):

4. Keep it tidy — separate memories per topic with projects:

   "Memorise ~/work/clientA into a project called clientA." "Using the clientA project, what were the agreed deliverables?"

Your memory lives in a folder on your computer (~/.memorised-them-all by default) and persists between chats. Re-running "memorise" updates it.

---

🎯 What can I use it for?

• 📚 Research & study — digest a pile of papers or a textbook, then ask for explanations, comparisons, and citations.
• 📑 Contracts & policies — load all your agreements and ask "which ones auto-renew?" or "what are the termination clauses?"
• 🗂️ Personal knowledge base — point it at years of notes, receipts, or manuals and actually find things.
• 🖼️ Scanned documents & images — it reads text from photos and scans (OCR) so they become searchable.
• 🔒 Sensitive material — legal, medical, financial, or confidential files that must never leave your machine.

---

✨ Why is it free of token cost?

When you normally share a document with Claude, the whole thing is sent into the conversation — and you pay (in tokens) for every word, every time. A few big PDFs can blow your whole context window.

Memorised them All flips that around:

• Converting, reading, and summarising your files happens on your computer.
• Claude only ever receives a tiny result — a count, a short summary, or a few relevant snippets (capped small).
• So memorising a giant folder, and asking about it again and again, stays near-zero context tokens.

It's the difference between mailing someone an entire library versus asking a librarian a question.

---

🔒 Is my data private?

Yes — that's the whole point. By default:

• ✅ 100% local. Your files are read, converted, and remembered on your own machine. Their contents are never sent to Claude's servers, to us, or to anyone.
• ✅ No telemetry, no tracking, no accounts, no API keys.
• ✅ Works fully offline. Disconnect the internet and it still memorises and answers.
• ✅ Open source (MIT). You (or anyone) can read exactly what it does.

The only times anything touches the network are clearly optional and on your command: installing/updating software, an occasional check for a new version (turn off with MTA_AUTO_UPDATE=off), or if you explicitly choose to point it at a remote AI backend. With the defaults, your documents stay with you. See SECURITY.md for the full threat model.

---

🛡️ Built to be reliable

It's been hardened through repeated, deliberate stress-testing so it stays calm on real, messy folders:

• It always finishes. A broken, enormous, or stuck file can't freeze the job — every file has a time limit and is skipped if it jams, so the rest still go through.
• One bad file won't sink the batch. Unreadable files, looping shortcuts, and odd or over-long filenames are skipped, never fatal.
• Your memory is crash-safe. If the computer is interrupted mid-write, your memory isn't corrupted or lost — writes are atomic, and anything that looks damaged is backed up before it's touched.
• It's the same every time. The engine is deterministic — memorising the same folder twice produces the identical memory, on any machine.
• It reads awkward files. Windows "Unicode" (UTF-16) text, archives (zip/rar — unpacked safely, duplicates detected), and legacy Bengali (Bijoy/SutonnyMJ) fonts are handled; media, fonts, and junk files are skipped cleanly.
• It can't be tricked into reading elsewhere. A shortcut planted in a folder that points outside that folder is ignored — a digest only ever reads what you pointed it at.

---

❓ Questions & troubleshooting

Is it really free?

Yes — the software is free and open-source (MIT), and it runs on your own computer, so there are no per-use fees or token charges. The only "cost" is a little of your computer's time and disk space.

Claude says it doesn't have the tool / it's not showing up.

Make sure the extension/plugin is installed and enabled, then fully restart Claude Desktop (or your Claude Code session). To confirm the engine itself works, run mta status in a terminal — it should print your setup. Still stuck? Run mta doctor.

The first "memorise" was slow.

The first run sets things up. Later runs are much faster, and re-memorising only processes what changed. There's no AI model to download or load — the engine is deterministic and starts instantly.

What files can it read?

PDFs, Word/Excel/PowerPoint, plain text/Markdown, HTML, CSV/JSON/XML, RTF, EPUB — plus archives (.zip/.tar/.gz natively; .rar/.7z when an extractor like unar is installed), which are unpacked safely and read. Beyond those, any other text-based file is digested too (source code, .log, .tex, …). Photos, video, audio, fonts, and junk files are skipped by default (scanned images can be OCR'd by setting MTA_SKIP_MEDIA=off if Tesseract is installed). Ask Claude to "list what's digestible in this folder" to see.

What languages does it understand?

Text in any language works (it's Unicode throughout). For scanned documents and images, OCR runs English + Bangla by default (eng+ben); set MTA_OCR_LANG to other Tesseract codes (e.g. eng+hin+ara). Any language pack you don't have installed is dropped automatically, so it never errors.

How do I delete a memory?

Tell Claude "forget the clientA project" (it asks you to name the project, on purpose). It deletes that project's memory from your disk — irreversibly.

Does it need an internet connection?

No. It's built to work completely offline. Internet is only used for optional, opt-in things like installing updates.

Does it use AI? Why are the summaries so plain?

No — and that's deliberate. Version 2 is fully deterministic: it extracts people, places, organisations, and facts with carefully-tuned rules (plain Python + maths), not an AI model. That means it always works (nothing to install, nothing to break, nothing to run out of memory), it's fast, and memorising the same folder twice gives the identical result. The trade-off is that summaries read more like structured notes than flowing prose — but every fact is grounded in your documents, and Claude (which IS the AI) does the smart reasoning at question time using the recalled facts.

---

🧰 The tools Claude gets

Once installed, Claude can use these eight tools on your behalf (you just talk normally — Claude picks the right one):

Tool	What it does for you
digest	Reads files/folders and builds (or updates) the memory.
convert	Just converts files to clean Markdown (no memory) — handy for exporting or fixing legacy Bengali.
recall	Answers a question from memory with a few relevant, cited snippets.
memory_overview	Gives the big picture — a synopsis and the main themes.
list_digestible	Shows which files in a folder it can read.
export_memory	Saves the memory as portable Markdown notes you can keep or share.
memory_status	Reports your local setup (models, tools, projects).
forget	Deletes a project's memory (you name it explicitly).

Every tool returns only small results — never your documents' contents.

---

🛠️ For power users

You don't need any of this to use the app — but it's here if you want it.

Command line (no Claude needed)

The same engine ships as an mta command:

mta digest ~/Documents/research        # build/update memory (deterministic, model-free)
mta recall "what about the Q3 budget?" # query it
mta overview                            # synopsis + themes
mta status                              # local stack health   ·   mta doctor  (fix deps)
mta export ./notes                      # export portable Markdown

Use it from other AI apps (OpenAI, Gemini, plain HTTP)

The same eight tools can be served beyond Claude:

mta serve --http     # MCP over HTTP (loopback + an auto-generated bearer token)
mta serve --rest     # plain JSON:  POST http://127.0.0.1:8765/tools/<name>
mta export-schema    # tool schemas as OpenAI / Gemini / OpenAPI 3.1 (no drift)
mta recipes          # copy-paste connection snippets for every client

Both HTTP modes are loopback-only by default and require a bearer token. See mta recipes for ready-to-paste setup.

Run it in Docker

A multi-arch image (amd64 + arm64) is published to GHCR:

docker run -d --name mta -p 127.0.0.1:8765:8765 -v mta-data:/data \
  ghcr.io/gru-953/memorised-them-all:latest
docker logs mta     # copy the printed bearer token + the `claude mcp add …` line

It serves the tools over MCP HTTP and keeps memory in the /data volume. Mount documents read-only (-v /path/to/docs:/docs:ro) and digest the in-container path.

Configuration

Everything has sensible defaults. Common knobs (set as environment variables):

Variable	Default	Meaning
MTA_HOME	~/.memorised-them-all	where memory is stored
MTA_SKIP_MEDIA	on	skip photos/video/audio (set off to OCR images with Tesseract)
MTA_SKIP_FONTS / MTA_SKIP_GDRIVE / MTA_SKIP_JUNK	on	skip font files / Google-Drive pointer stubs / .tmp,.DS_Store junk
MTA_ARCHIVE_RECURSIVE	on	unpack zip/tar/gz (+ rar/7z via unar/7z) recursively, with bomb + path-traversal guards
MTA_ARCHIVE_DEPTH / MTA_ARCHIVE_ENTRIES	8 / 100000	nesting depth / member-count caps for archives
MTA_OCR_LANG	eng+ben	OCR languages (Tesseract codes; missing packs dropped automatically)
MTA_BANGLA_LEGACY	on	auto-convert legacy Bengali (Bijoy/SutonnyMJ) to Unicode
MTA_CONVERT_TIMEOUT	120	per-file conversion timeout (seconds); a file that hangs the parser is skipped, never stalls the batch. 0 disables
MTA_MAX_FILE_MB	200	per-file size cap (also drives the archive budgets)
MTA_MEMORY_GB	auto	override detected RAM (for containers/VMs that misreport it)
MTA_WORKERS	auto	conversion workers (RAM/CPU-sized; 1 on small machines)
MTA_AUTO_UPDATE	on	daily MarkItDown update check (off to disable)
MTA_HTTP_*	off	options for the opt-in HTTP/REST servers

Why no AI model? (v2 design)

Earlier versions could optionally use local AI models (via Ollama) for extraction and search. Version 2 removed them on purpose. The deterministic engine:

• always works — nothing to download, install, crash, or run out of memory; the same on a 4 GB laptop and a 64 GB workstation;
• is reproducible — the same folder always produces the identical memory (great for auditing);
• is fast — no model loading, no GPU, instant startup;
• stays private & token-free — nothing ever leaves your machine, and Claude still only receives tiny slices.

The trade-off: extraction and search are rule-/keyword-based rather than semantic. In practice Claude compensates at question time — it reasons over the recalled facts. If you used v1.x with models: your old memories still load; re-memorise once (reset: true) to rebuild them with the deterministic engine.

Legacy Bengali (Bijoy / SutonnyMJ) → Unicode, and the convert command

Millions of Bengali documents were typed with the Bijoy keyboard in SutonnyMJ (and 110+ other ANSI fonts); read as plain text they come out as mojibake. Memorised them All upgrades them to standard Unicode Bengali automatically during conversion, so digest / recall / embeddings work on real text instead of garbage.

• Font-aware for Office files (.docx / .pptx / .xlsx): only runs whose font is a Bijoy-family font are converted, so mixed English + Bengali documents come out clean (the English is left exactly as-is). Plain text uses a conservative density check that never touches ordinary English.
• A faithful pure-Python port of the Mukti converter — no new dependency, fully local, on by default (MTA_BANGLA_LEGACY=off to disable).

Convert a folder to Markdown (with the legacy upgrade) without building memory:

mta convert ~/docs                 # writes ~/docs/markdown_converted/*.md
mta convert ~/docs --out ~/md_out  # …or choose the output folder

digest runs the very same conversion as its first step, so converting to Markdown is the default everywhere — reach for convert only when you want the .md files themselves.

How it works under the hood

convert (files → Markdown, locally; archives unpacked safely; duplicates deduped) → extract (entities, relations, facts — rule-based, deterministic) → graph (build + detect communities/themes) → summarise (layered: per-theme + a global synopsis, fact-joined) → index (deterministic vectors for search) → materialise (memory.md + per-doc notes). recall matches your question against the graph and returns the closest, capped, cited snippets. No models, no network — a digest always succeeds and is byte-for-byte reproducible. See CHANGELOG.md and SECURITY.md for details.

---

💻 Platforms

macOS (Apple-silicon optimised), Linux, and Windows · Python 3.10–3.12 · tested on all three in CI.

🙏 Credits & license

Built on the shoulders of MarkItDown, NetworkX, and the Model Context Protocol. Optional community-detection extras (python-igraph, leidenalg) are GPL-licensed and not installed by the MIT core. See ACKNOWLEDGEMENTS.md.

MIT licensed · made by GRU-953. Issues and contributions welcome — start with SECURITY.md for the security model.

_{100% local · token-free · free & open-source · your files never leave your machine.}