MenteDB: AI Agent Memory Database

Common errors

• Error: No prebuilt binary for your platform...

  cause The `mentedb` package includes a native Node.js addon, and `npm install` failed to find a precompiled binary for your operating system and architecture.
  fix Install Rust and `napi-rs` build tools, then try installing again. Alternatively, check the GitHub releases for prebuilt binaries for your specific platform or consult the project's documentation for supported environments.

• TypeError: MenteDB is not a constructor

  cause This error typically occurs when attempting to use CommonJS `require()` syntax to import `mentedb`, which is an ESM-first package.
  fix Ensure your project is configured for ES Modules (add `"type": "module"` to `package.json`) and use `import { MenteDB } from 'mentedb';` syntax.

• Error: Failed to open database at path...

  cause The specified `dataDir` path for `new MenteDB(dataDir)` is invalid, lacks write permissions, or points to a corrupted database file.
  fix Verify the `dataDir` path exists and is writable by the Node.js process. Ensure no other process is actively using the same database directory. If corruption is suspected, try deleting the directory and restarting (losing data).

Warnings

• breaking As a pre-1.0 release (currently v0.3.1), MenteDB's API is subject to frequent changes. Major and minor version bumps may introduce breaking changes without extensive migration guides.
  Fix: Always pin to exact versions (e.g., `npm install mentedb@0.3.1`) and thoroughly review release notes before upgrading in production environments. Regular dependency audits are recommended.
• gotcha If a prebuilt native binary is not available for your platform, `npm install` may fail. Building from source requires Rust and the `napi-rs` toolchain to be installed and correctly configured on your system.
  Fix: Ensure Rust and `napi-rs` are installed as per the `mentedb` README. Check `npm install` logs for specific compilation errors related to the native addon. Run `npm run build` in the `sdks/typescript` directory if troubleshooting.
• gotcha MenteDB's `store` and `search` methods rely on external embedding vectors. You must integrate a separate AI model (e.g., an LLM embedding API) to generate these `number[]` arrays before interacting with the database.
  Fix: Develop or integrate an embedding generation service (e.g., OpenAI, Cohere, custom model) to produce numerical vector representations of your memory content and queries. Pass these `number[]` arrays to `db.store()` and `db.search()`.

Install

• npm install mentedb npm
• yarn add mentedb yarn
• pnpm add mentedb pnpm

Imports

• MenteDB
  wrong:

  const MenteDB = require('mentedb');

  correct:

  import { MenteDB } from 'mentedb';

  MenteDB is an ESM-first package. CommonJS 'require' syntax is not supported for direct imports and will lead to errors.
• MemoryType

  import { MemoryType } from 'mentedb';

  Enums like MemoryType are exported as named exports.
• CognitionStream
  wrong:

  import CognitionStream from 'mentedb';

  correct:

  import { CognitionStream } from 'mentedb';

  CognitionStream is a named export, not a default export.
• EdgeType

  import { EdgeType } from 'mentedb';

  Enums like EdgeType are exported as named exports.

Quickstart

This quickstart demonstrates how to initialize MenteDB, store and search memories with embeddings, perform MQL recalls, and utilize its cognitive features like CognitionStream and TrajectoryTracker.

import { MenteDB, MemoryType, EdgeType, CognitionStream, TrajectoryTracker } from 'mentedb';

// Initialize your embedding model (example placeholder)
const embeddingFromYourModel = Array(1536).fill(0.123);
const queryEmbedding = Array(1536).fill(0.456);

async function runMenteDB() {
  // Open or create a database
  const db = new MenteDB('./my-agent-memory-data');
  console.log('MenteDB initialized.');

  // Store a memory
  const id = db.store({
    content: 'The deploy key rotates every 90 days',
    memoryType: MemoryType.Semantic,
    embedding: embeddingFromYourModel,
    tags: ['infra', 'security'],
  });
  console.log(`Stored memory with ID: ${id}`);

  // Vector similarity search
  const hits = db.search(queryEmbedding, 2);
  console.log('Search hits:', hits);

  // MQL recall with token budget
  const ctx = db.recall('RECALL similar("deploy key rotation") LIMIT 10');
  console.log('Recall context:', ctx.text, `(${ctx.totalTokens} tokens)`);

  // Relate memories (assuming 'otherId' exists, e.g., from another store call)
  // const otherId = db.store({ content: 'Another related fact', memoryType: MemoryType.Semantic, embedding: embeddingFromYourModel });
  // db.relate(id, otherId, EdgeType.Supersedes);
  // console.log(`Related ${id} to ${otherId}`);

  // Simulate an LLM token stream for cognition
  const stream = new CognitionStream();
  const llmTokens = ['Hello', ' ', 'world', '!'];
  for (const token of llmTokens) {
    stream.feedToken(token);
  }
  console.log('Drained CognitionStream buffer:', stream.drainBuffer());

  // Track reasoning trajectory
  const tracker = new TrajectoryTracker();
  tracker.recordTurn('Discuss JWT auth', 'investigating', ['Which algorithm?', 'Token lifetime?']);
  tracker.recordTurn('Token lifetime', 'decided:15 minutes');
  console.log('Resume context:', tracker.getResumeContext());
  console.log('Predicted next topics:', tracker.predictNextTopics());

  // Forget a memory
  db.forget(id);
  console.log(`Forgot memory with ID: ${id}`);

  // Close the database
  db.close();
  console.log('MenteDB closed.');
}

runMenteDB().catch(console.error);