# dimple — memory for agents

A local-first memory system for AI agents: store text memories and whole
codebases, retrieve them with hybrid semantic + lexical search, and let a
self-organizing **topic tree + artifact graph** keep everything structured
as it grows. Everything runs locally — embeddings use
[Transformers.js](https://huggingface.co/docs/transformers.js) ONNX models
on your CPU (no API keys), and data lives in SQLite files on disk.

> **Documentation**: [dimple.ponraaj.me](https://dimple.ponraaj.me) —
> quickstart, architecture, config reference, changelog ·
> **Package**: [npmx.dev/package/@ponraaj/dimple](https://npmx.dev/package/@ponraaj/dimple) ·
> **Status**: alpha (`0.0.0-alpha.n`) — the API is stabilizing.

## Install

```bash
npm install -g @ponraaj/dimple
```

Local embeddings auto-install on first use (`@huggingface/transformers` is
an optional peer — hosted-only consumers never pull its postinstall tree).
`embedding.models[].autoInstall: false` disables it.

## Quickstart

```bash
dimple init                      # write the full annotated config
dimple write --key deploy-1 --content "the pipeline deploys on push"
dimple query "how does the pipeline deploy" --limit 3
dimple index ./src               # tree-sitter: one unit per file + definition
```

## Commands

| Command                                                | What it does                                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `dimple init`                                          | Write a valid annotated `dimple.jsonc`                                               |
| `dimple write` / `get` / `forget` / `update-embedding` | Memory CRUD                                                                          |
| `dimple query`                                         | Hybrid search (`--json`, budgets, profiles, `--content-type`)                        |
| `dimple index`                                         | Codebase ingestion (idempotent; renames/deletes reconcile)                           |
| `dimple graph …`                                       | `add-edge` / `confirm` / `reject` / `expire` / `candidates` / `coverage` / `explain` |
| `dimple dream` / `repair`                              | Consolidation + maintenance jobs                                                     |
| `dimple health`                                        | Topic-tree invariant health                                                          |
| `dimple serve`                                         | Local read-only dashboard                                                            |
| `dimple db-schema`                                     | Print the table/column map                                                           |
| `dimple mcp`                                           | MCP server (below)                                                                   |
| `dimple upgrade`                                       | Check the npm registry and self-update (`--check` to only print)                     |

Output: stdout is data-only (logs go to stderr); `--json` is compact
(embeddings omitted, `--embedding` opts in).

## MCP server (`dimple mcp`)

Expose dimple to any MCP client (Claude Desktop, Codex, Cursor) over the
2026-07-28 protocol — modern-only:

```bash
dimple mcp            # stdio (client-launched)
dimple mcp --print    # client config block
dimple mcp start      # loopback daemon → status / reload / stop
```

Exactly two tools: **`search`** discovers the method surface (signatures,
when-to-use, examples), and **`code.exec`** runs TS/JS in a secure
fresh-per-exec sandbox with the whole API as a `dimple` namespace:

```js
const [m, hits] = await Promise.all([
  dimple.write({ logicalKey: "k", content: "hello" }),
  dimple.search({ query: "hello", limit: 3 }),
]);
__return({ id: m.id, hits: hits.length });
```

`secure-exec` (+ `@secure-exec/sidecar`) is an optional peer for real
sandboxed runs; `typescript` ^5 only for TS guests. Full guide:
[MCP server & code mode](https://dimple.ponraaj.me/guides/mcp/).

## Configuration

`dimple init` writes the full annotated schema; `${ENV_VAR}` placeholders
keep tokens out of files. Every section (store / jobs / embeddings /
topics / graph / llm / logging / Turso) is documented on the docs site:
[Configuration reference](https://dimple.ponraaj.me/reference/config/).

## Storage & logs

Databases live at `.dimple/` next to your config (`dimple.db` + `jobs.db`);
logs are structured JSONL in the same directory. The architecture (topic
tree, retrieval, graph, concepts, dream, durability) is explained on the
docs site.

## Changelog

[Release history](https://dimple.ponraaj.me/changelog/cli/) · repository
[`CHANGELOG.md`](./CHANGELOG.md)