kmail-memo-agent

v1.0.0 · stable · knowledge

unified memory + semantic grep for AI agents

about

Merges memory and semantic grep into one tool. Store and recall memories

by meaning, and index your whole org-memory to answer "where did we decide

X?" in one keystroke. Respects file permissions. Forgets nothing unless

you tell it to. Configure any of 7 embedding providers with a wizard.

what it does

Memory by meaning: `kmail-memo-agent put "…"` stores a memory with its embedding written at the same time, and `get` recalls it by meaning rather than by keyword.
Semantic grep over files: `index ~/notes` walks a directory and `search "where did we decide X?"` queries it by meaning, respecting file permissions and skipping .gitignore'd paths.
Seven embedding providers: `config --wizard` configures ollama (the default, and the only one needing no API key), openai, azure, gemini, mistral, custom or local — each with its own model, URL and vector dimensions.
Local SQLite and HNSW: Memories and file chunks live in a store directory (~/.kmail-memo-agent/<name> by default): SQLite for text, an hnswlib cosine index of up to 1,000,000 elements for vectors.
Forget and compact on purpose: `forget <id>` soft-deletes a single memory and `compact` reclaims space and rebuilds the index — nothing is dropped unless you ask for it.
Usable as a library: `import { MemoAgent } from 'kmail-memo-agent'` exposes the same put / get / indexAll / searchFiles calls the CLI is built on, with a configurable store and scope.

install

npm — global install

npm install -g kmail-memo-agent

Installs the `kmail-memo-agent` command. Needs Node.js 20 or newer. better-sqlite3 and hnswlib-node are native modules, so a compiler toolchain is required where npm finds no prebuilt binary for your platform and Node version.

Configure the embedding provider

kmail-memo-agent config --wizard

Interactive wizard: choose a provider and set model, URL and key. `config --providers` lists all seven with their defaults and dimensions — ollama on http://localhost:11434 with nomic-embed-text (768 dims) needs no key.

Store and recall a memory

kmail-memo-agent put "Customer prefers email over Slack"
kmail-memo-agent get "how does the customer like to be contacted?"

Works out of the box after `config --init`: the store defaults to ~/.kmail-memo-agent/<name> and --store moves it, while the file-walk scope defaults to the directory you run in.

Index a directory of notes

kmail-memo-agent index ~/notes
kmail-memo-agent search "where did we decide to use TypeScript?" -k 5

The first run embeds every file and builds the HNSW index; `status` prints index statistics and `reindex` rebuilds the index and re-walks the scope.

As a library

npm install kmail-memo-agent

Adds the package to a project so an agent can call MemoAgent directly instead of shelling out — the CLI is a front over the same API.

synopsis

kmail-memo-agent <put|get|index|search> [--store=path]

changelog

v1.0.0merged memo-vec + agent-grep into one tool
v0.9.0interactive config wizard + 7 embedding providers
v0.8.0Ollama is the default provider, no API key needed