amem.sh

Shared knowledge for agents and humans.

amem is a local-first knowledge engine. It captures references (arXiv papers, PDFs, web pages), compiles them into structured wiki notes with SHA-256 provenance, and serves them to AI agents over MCP. Everything runs on your Mac — no cloud.

Why amem

Frontier models write better papers when they can cite real sources. Humans maintain better notes when capture is friction-free. amem serves both audiences from one knowledge base:

For agents: MCP tools amem_capture, amem_compile, amem_cite, amem_recall — grounded citations with verifiable provenance
For humans: a CLI and a Chrome extension that drop into your existing workflow, storing everything as readable markdown under ~/.amem/

Relationship to aide.sh

aide orchestrates agents; amem gives them memory. The two are complementary:

Layer	Tool	Concern
Orchestration	aide.sh	Dispatch, budgets, teams
Knowledge	amem.sh	Capture, compile, recall

aide can use amem as its memory sync method ([sync.memory] method = "amem" in aide.toml).

Quick links

Install
Quick Start
MCP Tools
GitHub: amem-sh · amem-extension · amem-site · amem-hq

Installation

Prerequisites

macOS (primary target) or Linux
Rust toolchain (cargo)
Ollama running locally — required for the compile step
pdftotext (from poppler) — brew install poppler

Install the CLI

cargo install --git https://github.com/yiidtw/amem-sh

Or from a local checkout:

git clone git@github.com:yiidtw/amem-sh.git
cd amem-sh
cargo install --path .

Verify

amem --version
amem --help

Pull an Ollama model

ollama pull llama3.1

Override the default model with AMEM_OLLAMA_MODEL=<name> if needed.

Quick Start — capture your first paper
Concepts — how amem thinks

Quick Start

Capture a paper, compile it into a wiki note, and recall it.

1. Capture

amem capture https://arxiv.org/abs/1706.03762

Downloads the PDF to ~/.amem/raw/ and prints a cite key (e.g., vaswani2017attention).

2. Compile

amem compile vaswani2017attention

Parses the PDF, chunks it with SHA-256 provenance, runs Ollama paraphrase passes, and writes ~/.amem/wiki/{ts}_vaswani2017attention.md.

3. Recall

amem recall "attention mechanism"

Grep-searches your wiki and returns excerpts with cite keys.

4. Cite

amem cite vaswani2017attention --format bibtex

Prints a formatted citation.

5. Hook it up to Claude

claude mcp add amem -- amem mcp serve

Then ask Claude: “Cite vaswani2017attention in APA format using the amem MCP server.”

MCP Tools — the four tools agents use
Storage Layout — what’s in ~/.amem/

Concepts

Knowledge, not chat logs

Most “second brain” tools store a stream of captures — articles, notes, clippings — and hope you can find them later. amem does something different: it compiles captures into wiki notes with verbatim quotes and verifiable provenance. The wiki is the product; the raw captures are just source material.

This follows Andrej Karpathy’s recommendation of maintaining a personal wiki as the substrate for long-term thinking.

Dual audience

amem serves both agents (over MCP) and humans (via CLI + extension) from the same store. An agent citing a paper sees the same markdown a human sees. There’s no hidden “agent memory” that drifts from what’s on disk.

Provenance by construction

Every chunk carries a SHA-256 hash of its source. If the original file changes, amem verify detects drift. Citations stay grounded.

Offline-first

Zero cloud dependencies by default. Ollama runs locally. The only network calls are to fetch papers from their public URLs (arXiv, DOI resolvers). You can operate amem entirely air-gapped after initial capture.

Three interfaces

CLI — amem capture, amem compile, amem recall, amem cite
MCP server — amem_capture, amem_compile, amem_cite, amem_recall for agents
Chrome extension — one-click web page capture + self-recorded demos

MCP Tools

amem exposes four MCP tools over stdio. Start the server with amem mcp serve.

amem_capture

Download a paper and generate a cite key.

Input: url (string) — arXiv URL, DOI, PDF URL, or local file path

Output: cite_key (string), raw_path (string)

amem_compile

Parse + chunk + paraphrase a captured source into a wiki note.

Input: cite_key (string)

Output: wiki_path (string), chunk_count (number)

amem_cite

Format a citation in a supported style.

Input: cite_key (string), format (string, one of bibtex / apa / mla / chicago / ieee)

Output: citation (string)

amem_recall

Search the wiki for matching chunks.

Input: query (string), limit (number, optional, default 10)

Output: list of {cite_key, excerpt, sha256, score}

Register with Claude

claude mcp add amem -- amem mcp serve

Register with other MCP clients

Any MCP client that supports stdio transport works. Point it at the amem mcp serve command.

Storage Layout

Everything lives under ~/.amem/.

~/.amem/
├── raw/                          # original captures
│   ├── vaswani2017attention.pdf
│   └── ...
├── wiki/                         # compiled notes
│   ├── 20260418_vaswani2017attention.md
│   └── ...
└── index.md                      # auto-maintained TOC

raw/

Original files exactly as downloaded. amem verify re-hashes against these.

wiki/

Compiled markdown notes. One file per cite key. Filename prefix is the compile timestamp so recompiles preserve history (you can git init ~/.amem/wiki && git commit if you want versioning).

index.md

Auto-regenerated on every amem compile — a flat list of all cite keys with paths. Never edit by hand.

Custom location

Override with AMEM_HOME=<path> (planned — not yet wired up).

Citation Formats

amem cite <cite_key> --format <fmt> supports:

Format	Flag	Use
BibTeX	`bibtex`	LaTeX papers
APA	`apa`	Social sciences
MLA	`mla`	Humanities
Chicago	`chicago`	History, arts
IEEE	`ieee`	Engineering

Default: bibtex.

Example

$ amem cite vaswani2017attention --format apa
Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N.,
Kaiser, Ł., & Polosukhin, I. (2017). Attention is all you need.

Metadata sources

arXiv API (for arXiv papers)
CrossRef (for DOIs)
Extracted from PDF metadata as fallback

Chrome Extension

The amem-extension is a Chrome MV3 side-panel extension for capturing web pages into your amem knowledge base.

Status

Bridge mode (Day 2 — in progress): extension talks to amem locally over WebSocket on port 7600. Extension captures → bridge forwards → amem stores.

Standalone mode (Day 3 — planned): when amem isn’t running, the extension falls back to Google Drive backup. Requires a new OAuth client (not shipped yet).

Install

The extension will be published on the Chrome Web Store as a new listing under the same developer account as crossmem (the v0 prototype). crossmem remains published and unchanged.

Published URL will appear here after approval.

Self-recording workflow

The extension ships with a self-recording skeleton: chrome.runtime.sendMessage({cmd: 'start_recording'}) triggers a tabCapture session via the offscreen document, producing amem-recording-<iso>.webm in Downloads.

This is how amem produces its own demo videos — the extension records itself being used. See Self-Recording Workflow.

Self-Recording Workflow

One of amem’s foundational features: amem is its own best demo. The extension records itself being used, producing the marketing video and Chrome Web Store listing assets automatically.

How it works

An orchestrator (human or agent) sends {cmd: 'start_recording'} to the extension’s background service worker.
The background worker opens an offscreen.html document with a MediaRecorder consuming tabCapture.
The agent then drives the extension UI through the bridge — clicking the side panel, capturing pages, showing the wiki.
{cmd: 'stop_recording'} finalizes the .webm and saves to Downloads as amem-recording-<iso>.webm.

Why this matters

Demos stay in sync with reality — the recording shows the current UI, not a stale screenshot
Chrome Web Store listings can be refreshed in minutes
Agents learn to operate amem by watching their own recordings

Status

The recording skeleton is shipped. The agent-driven recording scenarios are Day 2 work. The complete workflow ships alongside the Chrome Web Store submission.

amem capture

Download a paper or PDF into ~/.amem/raw/ and generate a cite key.

Usage

amem capture <url> [--doi <doi>] [--cite-key <key>]

Arguments

<url> — arXiv URL, DOI, PDF URL, or local file path
--doi <doi> — override DOI lookup (useful when a PDF URL doesn’t resolve)
--cite-key <key> — override the auto-generated cite key

Examples

amem capture https://arxiv.org/abs/1706.03762
amem capture https://example.com/paper.pdf
amem capture 10.1038/nature14539 --doi 10.1038/nature14539
amem capture ./local-paper.pdf --cite-key smith2024local

Output

Prints the cite key on success. Exits non-zero on failure.

amem compile

Parse a captured source, chunk with SHA-256 provenance, run Ollama paraphrase, and emit a wiki note.

Usage

amem compile <cite_key>

Environment

AMEM_OLLAMA_MODEL — override the paraphrase model (default: llama3.1)

Output

Writes ~/.amem/wiki/{timestamp}_{cite_key}.md and updates ~/.amem/index.md.

Example

$ amem compile vaswani2017attention
Chunked into 47 chunks. Ollama paraphrase 47/47 ok.
Wrote ~/.amem/wiki/20260418_vaswani2017attention.md

amem recall

Grep-search compiled wiki notes and return excerpts.

Usage

amem recall <query> [--limit N]

Arguments

<query> — free-text search term
--limit N — max results (default 10)

Example

$ amem recall "attention mechanism" --limit 3
vaswani2017attention (sha256:a1b2c3…): "…the Transformer, based solely on attention mechanisms…"
bahdanau2014neural  (sha256:d4e5f6…): "…a neural machine translation model learns to pay attention to…"

amem cite

Print a formatted citation for a captured source.

Usage

amem cite <cite_key> [--format bibtex|apa|mla|chicago|ieee]

Default format: bibtex.

amem mcp serve

Start the MCP stdio server. Exposes amem_capture, amem_compile, amem_cite, amem_recall to any MCP client.

Usage

amem mcp serve

Register with Claude

claude mcp add amem -- amem mcp serve

Philosophy

Wiki as substrate

Karpathy argues that a personal wiki — verbatim quotes, paraphrase, cross-links — is the durable substrate of long-term thinking. Apps come and go; markdown with provenance stays readable for decades.

amem treats the wiki as the product, not a byproduct. Capture is just staging; compile is the commitment.

Offline-first, always

Cloud dependencies are a liability. amem runs entirely on a user’s Mac: Ollama for LLM, pdftotext for PDF parsing, local disk for storage. The only network calls fetch papers from their canonical URLs.

This matters for three reasons:

Sovereignty — your knowledge base doesn’t evaporate when a vendor pivots
Speed — local I/O beats round-trips
Reproducibility — SHA-256 provenance only means something if the source sits next to the hash

Dual audience

MCP for agents, CLI + extension for humans — same store, one source of truth. If an agent cites a chunk, a human can read that exact chunk by grep-ing ~/.amem/wiki/.

Complement, don’t compete

aide orchestrates agents. amem gives them memory. Neither duplicates the other. [sync.memory] method = "amem" in an aide.toml is the contract.

No legacy

amem is a clean v1 rewrite of crossmem. No code was ported verbatim; every module was reconsidered against these principles. crossmem remains published as v0 for historical continuity.

MCP Protocol

amem implements the Model Context Protocol over stdio using the rmcp Rust crate.

Transport

Stdio only (Day 1)
HTTP/WebSocket bridge for the Chrome extension is Day 2 work

Server identification

server_name: amem
server_version: matches the crate version

Tools

See MCP Tools for input/output schemas.

Error conventions

Malformed inputs → InvalidParams
Missing cite_key → ResourceNotFound
Ollama unreachable → Internal with hint start ollama
File IO errors → Internal with the OS error

Session model

Each amem mcp serve process is one session. No state shared between sessions beyond what’s on disk under ~/.amem/.

Relationship to aide.sh

amem and aide are complementary layers of the same system.

[sync.memory]
method = "amem"
conflict = "causal"

When this is set, aide uses amem as its cross-agent memory substrate. Agents share a wiki; a fact learned by one agent is available to all.

Division of labor

Concern	aide	amem
Which agent runs?	✓	—
How much budget?	✓	—
What does the agent read?	—	✓
Where are citations stored?	—	✓
How are secrets gated?	✓	—
What’s the SHA-256 of chunk 7?	—	✓

Using one without the other

amem alone: CLI + extension + MCP. Useful for human-led research and single-agent setups.
aide alone: works fine, just without shared knowledge. Agents reason from their own seed context.
Both together: the full stack.

Keyboard shortcuts

amem.sh