mentedb 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# mentedb
+
+The mind database for AI agents. TypeScript/Node.js SDK powered by napi-rs.
+
+MenteDB is a purpose built database engine for AI agent memory. It provides
+vector similarity search, a typed knowledge graph, token budget aware context
+assembly, and cognitive features such as contradiction detection and trajectory
+tracking. This package delivers the full Rust engine as a native Node.js addon
+with zero runtime dependencies.
+
+## Install
+
+```bash
+npm install mentedb
+```
+
+The package ships a prebuilt native binary. If no prebuild is available for your
+platform, `npm run build` compiles from source (requires Rust and
+[napi-rs](https://napi.rs)).
+
+## Quick start
+
+```typescript
+import { MenteDB, MemoryType, EdgeType } from 'mentedb';
+
+const db = new MenteDB('./my-agent-memory');
+
+// Store a memory
+const id = db.store({
+  content: 'The deploy key rotates every 90 days',
+  memoryType: MemoryType.Semantic,
+  embedding: embeddingFromYourModel,
+  tags: ['infra', 'security'],
+});
+
+// Vector similarity search
+const hits = db.search(queryEmbedding, 5);
+
+// MQL recall with token budget
+const ctx = db.recall('RECALL similar("deploy key rotation") LIMIT 10');
+
+// Relate memories
+db.relate(id, otherId, EdgeType.Supersedes);
+
+// Forget a memory
+db.forget(id);
+
+// Close the database
+db.close();
+```
+
+## Cognitive features
+
+### CognitionStream
+
+Monitor an LLM token stream for contradictions and reinforcements against
+stored facts.
+
+```typescript
+import { CognitionStream } from 'mentedb';
+
+const stream = new CognitionStream(1000);
+for (const token of llmTokens) {
+  stream.feedToken(token);
+}
+const text = stream.drainBuffer();
+```
+
+### TrajectoryTracker
+
+Track the reasoning arc of a conversation and predict upcoming topics.
+
+```typescript
+import { TrajectoryTracker } from 'mentedb';
+
+const tracker = new TrajectoryTracker();
+
+tracker.recordTurn('JWT auth design', 'investigating', [
+  'Which algorithm?',
+  'Token lifetime?',
+]);
+tracker.recordTurn('Token lifetime', 'decided:15 minutes');
+
+const resume = tracker.getResumeContext();
+const next = tracker.predictNextTopics();
+```
+
+## API reference
+
+### `MenteDB`
+
+| Method | Description |
+|--------|-------------|
+| `new MenteDB(dataDir)` | Open or create a database at the given path. |
+| `store(options)` | Store a memory. Returns its UUID string. |
+| `recall(query)` | Recall memories via an MQL query. Returns `RecallResult`. |
+| `search(embedding, k)` | Vector similarity search. Returns `SearchResult[]`. |
+| `relate(source, target, edgeType?, weight?)` | Create a typed edge between two memories. |
+| `forget(memoryId)` | Remove a memory by ID. |
+| `close()` | Flush and close the database. |
+
+### `CognitionStream`
+
+| Method | Description |
+|--------|-------------|
+| `new CognitionStream(bufferSize?)` | Create a token stream monitor. |
+| `feedToken(token)` | Push a token into the ring buffer. |
+| `drainBuffer()` | Drain and return the accumulated text. |
+
+### `TrajectoryTracker`
+
+| Method | Description |
+|--------|-------------|
+| `new TrajectoryTracker(maxTurns?)` | Create a trajectory tracker. |
+| `recordTurn(topic, decisionState, openQuestions?)` | Record a conversation turn. |
+| `getResumeContext()` | Build a resume context string. |
+| `predictNextTopics()` | Predict the next likely topics. |
+
+## Types
+
+```typescript
+enum MemoryType {
+  Episodic, Semantic, Procedural, AntiPattern, Reasoning, Correction
+}
+
+enum EdgeType {
+  Caused, Before, Related, Contradicts, Supports, Supersedes, Derived, PartOf
+}
+
+interface StoreOptions {
+  content: string;
+  memoryType?: MemoryType;
+  embedding?: number[];
+  agentId?: string;
+  tags?: string[];
+}
+
+interface RecallResult {
+  text: string;
+  totalTokens: number;
+  memoryCount: number;
+}
+
+interface SearchResult {
+  id: string;
+  score: number;
+}
+```
+
+## Building from source
+
+```bash
+cd sdks/typescript
+cargo check          # verify Rust compiles
+npm run build        # build the native addon
+npm test             # run tests
+```
+
+## License
+
+Apache 2.0

package/npm/client.ts

@@ -0,0 +1,143 @@
+import {
+  MemoryType,
+  EdgeType,
+  type StoreOptions,
+  type RecallResult,
+  type SearchResult,
+} from './types';
+
+let nativeBinding: any;
+
+try {
+  nativeBinding = require('../mentedb.node');
+} catch {
+  nativeBinding = null;
+}
+
+function requireNative(): any {
+  if (!nativeBinding) {
+    throw new Error(
+      'Native extension not loaded. Build with: npm run build'
+    );
+  }
+  return nativeBinding;
+}
+
+/**
+ * MenteDB client. Wraps the native Rust database engine and exposes a
+ * TypeScript-friendly API for storing, recalling, searching, relating, and
+ * forgetting memories.
+ */
+export class MenteDB {
+  private native: any;
+
+  constructor(dataDir: string = './mentedb-data') {
+    const binding = requireNative();
+    this.native = new binding.MenteDB(dataDir);
+  }
+
+  /** Store a memory and return its UUID. */
+  store(options: StoreOptions): string {
+    const {
+      content,
+      memoryType = MemoryType.Episodic,
+      embedding = [],
+      agentId,
+      tags,
+    } = options;
+    return this.native.store(content, memoryType, embedding, agentId, tags);
+  }
+
+  /** Recall memories using an MQL query string. */
+  recall(query: string): RecallResult {
+    return this.native.recall(query);
+  }
+
+  /** Vector similarity search returning top-k results. */
+  search(embedding: number[], k: number = 10): SearchResult[] {
+    return this.native.search(embedding, k);
+  }
+
+  /** Create a typed, weighted edge between two memories. */
+  relate(
+    source: string,
+    target: string,
+    edgeType: EdgeType = EdgeType.Related,
+    weight: number = 1.0,
+  ): void {
+    this.native.relate(source, target, edgeType, weight);
+  }
+
+  /** Remove a memory by ID. */
+  forget(memoryId: string): void {
+    this.native.forget(memoryId);
+  }
+
+  /** Flush all data and close the database. */
+  close(): void {
+    this.native.close();
+  }
+}
+
+/**
+ * Monitors an LLM token stream for contradictions, forgotten facts,
+ * corrections, and reinforcements.
+ */
+export class CognitionStream {
+  private native: any;
+
+  constructor(bufferSize: number = 1000) {
+    const binding = requireNative();
+    this.native = new binding.JsCognitionStream(bufferSize);
+  }
+
+  /** Push a token into the stream buffer. */
+  feedToken(token: string): void {
+    this.native.feedToken(token);
+  }
+
+  /** Drain the accumulated buffer and return its content. */
+  drainBuffer(): string {
+    return this.native.drainBuffer();
+  }
+}
+
+/**
+ * Tracks the reasoning arc of a conversation and predicts next topics.
+ */
+export class TrajectoryTracker {
+  private native: any;
+
+  constructor(maxTurns: number = 100) {
+    const binding = requireNative();
+    this.native = new binding.JsTrajectoryTracker(maxTurns);
+  }
+
+  /**
+   * Record a conversation turn.
+   *
+   * `decisionState` accepts one of:
+   *   - `"investigating"`
+   *   - `"interrupted"`
+   *   - `"completed"`
+   *   - `"narrowed:<choice>"`
+   *   - `"decided:<decision>"`
+   */
+  recordTurn(
+    topic: string,
+    decisionState: string,
+    openQuestions: string[] = [],
+  ): void {
+    this.native.recordTurn(topic, decisionState, openQuestions);
+  }
+
+  /** Get a resume context string describing the current trajectory. */
+  getResumeContext(): string | null {
+    return this.native.getResumeContext() ?? null;
+  }
+
+  /** Predict the next likely topics based on trajectory. */
+  predictNextTopics(): string[] {
+    return this.native.predictNextTopics();
+  }
+}

package/npm/index.ts

@@ -0,0 +1,3 @@
+export { MenteDB, CognitionStream, TrajectoryTracker } from './client';
+export { MemoryType, EdgeType } from './types';
+export type { RecallResult, SearchResult, StoreOptions } from './types';

package/npm/types.ts

@@ -0,0 +1,38 @@
+export enum MemoryType {
+  Episodic = 'episodic',
+  Semantic = 'semantic',
+  Procedural = 'procedural',
+  AntiPattern = 'anti_pattern',
+  Reasoning = 'reasoning',
+  Correction = 'correction',
+}
+
+export enum EdgeType {
+  Caused = 'caused',
+  Before = 'before',
+  Related = 'related',
+  Contradicts = 'contradicts',
+  Supports = 'supports',
+  Supersedes = 'supersedes',
+  Derived = 'derived',
+  PartOf = 'part_of',
+}
+
+export interface RecallResult {
+  text: string;
+  totalTokens: number;
+  memoryCount: number;
+}
+
+export interface SearchResult {
+  id: string;
+  score: number;
+}
+
+export interface StoreOptions {
+  content: string;
+  memoryType?: MemoryType;
+  embedding?: number[];
+  agentId?: string;
+  tags?: string[];
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mentedb",
+  "version": "0.1.0",
+  "description": "The mind database for AI agents",
+  "main": "npm/index.js",
+  "types": "npm/index.d.ts",
+  "scripts": {
+    "build": "napi build --release",
+    "test": "jest"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nambok/mentedb"
+  },
+  "keywords": [
+    "database",
+    "ai",
+    "agents",
+    "memory",
+    "rust",
+    "vector",
+    "knowledge-graph"
+  ],
+  "napi": {
+    "name": "mentedb",
+    "triples": {}
+  }
+}