Quickstart

In this tutorial, we install the CLI, write one memory, and find it again from the terminal. The default configuration uses a local database and the Transformers.js embedding provider.

Before you start

You need Node.js or Bun with npm package support. The first install downloads a package and an embedding model, so you also need an internet connection.

Install the CLI

Install the CLI globally:

npm install --global @ponraaj/dimple

Or use Bun:

bun add --global @ponraaj/dimple

Create a project directory and generate the starter configuration:

mkdir agent-memory
cd agent-memory
dimple init

You should now have dimple.jsonc in the directory. The default database files go under .dimple/.

Write and search a memory

Write a memory with a stable key:

dimple write "The deploy pipeline runs on every push" --key deploy-pipeline

Search for it in natural language:

dimple query "When does the deploy pipeline run?" --limit 3

The query embeds your text and searches the vector index and the keyword index. The CLI prints the ranked results, and the memory you just wrote should come first. Add --json when another program needs structured output.

Use the SDK

Install the SDK in a JavaScript or TypeScript project. The SDK reads the same dimple.jsonc file.

npm install @ponraaj/dimple-sdk

import { makeDimple } from "@ponraaj/dimple-sdk";

const dimple = await makeDimple({ config: "./dimple.jsonc" });

try {
  await dimple.write({
    logicalKey: "deploy-pipeline",
    content: "The deploy pipeline runs on every push",
  });

  const results = await dimple.query("When does the deploy pipeline run?", {
    limit: 3,
  });

  console.log(results);
} finally {
  await dimple.dispose();
}

dispose() stops the worker and closes the database. Call it when the application shuts down.

Next steps

• Read the CLI guide for common commands and options.
• Index a source tree with the indexing guide.
• Choose an embedding provider or a remote database in the configuration reference.