@slorenzot/memento-core

Core memory engine with SQLite FTS5 search, session management, and observation persistence for AI coding agents.

🚀 Installation

# Using Bun (recommended)
bun add @slorenzot/memento-core

# Using npm
npm install @slorenzot/memento-core

💡 Basic Usage

TypeScript

import { MemoryEngine } from '@slorenzot/memento-core';

// Initialize memory engine
const memory = new MemoryEngine('./data/memento.db');

// Create an observation
const observation = await memory.createObservation({
  title: 'Architecture decision',
  content: 'Use SQLite as the database engine',
  type: 'decision',
  topicKey: 'architecture',
  projectId: 'my-project'
});

console.log('Observation saved:', observation);

Shell/Bun

# Run TypeScript script with memory engine
bun run memory-script.ts

🔧 Core API

Main Class

MemoryEngine(dbPath?: string)

Memory engine constructor.

Parameters:

• dbPath (optional): Path to the SQLite database file. Default: './data/memento.db'

Example:

const memory = new MemoryEngine('./custom/path.db');

Observation Methods

createObservation(data)

Creates a new observation in memory.

Parameters:

{
  title: string;
  content: string;
  type: 'decision' | 'bug' | 'discovery' | 'note';
  topicKey?: string | null;
  projectId: string;
  sessionId?: number;
  metadata?: Record<string, unknown>;
}

Returns: Promise<Observation>

Example:

const observation = await memory.createObservation({
  title: 'Bug found',
  content: 'Server connection error',
  type: 'bug',
  projectId: 'project-123',
  metadata: { severity: 'high', priority: 1 }
});

search(params)

Searches observations using FTS5 full-text search.

Parameters:

{
  query?: string;
  type?: 'decision' | 'bug' | 'discovery' | 'note';
  projectId?: string;
  topicKey?: string;
  limit?: number;
  offset?: number;
}

Returns: Promise<SearchResult>

Example:

const results = await memory.search({
  query: 'database architecture',
  type: 'decision',
  projectId: 'project-123',
  limit: 10
});

console.log(`Found ${results.total} observations:`);
results.observations.forEach(obs => console.log(obs.title));

getObservation(id)

Gets an observation by its ID.

Parameters:

• id: Numeric ID of the observation

Returns: Promise<Observation | null>

Example:

const observation = await memory.getObservation(123);
if (observation) {
  console.log('Observation found:', observation.title);
}

updateObservation(id, updates)

Updates an existing observation.

Parameters:

• id: Numeric ID of the observation
• updates: Object with fields to update

Returns: Promise<Observation>

Example:

const updated = await memory.updateObservation(123, {
  title: 'Updated title',
  content: 'Modified content'
});

deleteObservation(id)

Deletes an observation by its ID.

Parameters:

• id: Numeric ID of the observation

Returns: Promise<void>

Example:

await memory.deleteObservation(123);
console.log('Observation deleted');

Session Methods

createSession(data)

Creates a new session for conversation tracking.

Parameters:

{
  projectId: string;
  metadata?: Record<string, unknown>;
}

Returns: Promise<Session>

Example:

const session = await memory.createSession({
  projectId: 'my-project',
  metadata: { agent: 'claude', userId: 'user-123' }
});

console.log('Session started:', session.uuid);

getSession(id)

Gets a session by its ID.

Parameters:

• id: Numeric ID of the session

Returns: Promise<Session | null>

Example:

const session = await memory.getSession(456);
if (session) {
  console.log('Session found:', session.uuid);
}

endSession(id)

Ends an active session.

Parameters:

• id: Numeric ID of the session

Returns: Promise<Session>

Example:

const endedSession = await memory.endSession(456);
console.log('Session ended:', endedSession.endedAt);

Close Method

close()

Closes the database connection.

Returns: void

Example:

// On application cleanup
memory.close();

📝 Core Types

interface Observation {
  id: number;
  uuid: string;
  sessionId: number;
  title: string;
  content: string;
  type: 'decision' | 'bug' | 'discovery' | 'note';
  topicKey: string | null;
  projectId: string;
  createdAt: Date;
  metadata: Record<string, unknown>;
}

interface Session {
  id: number;
  uuid: string;
  projectId: string;
  startedAt: Date;
  endedAt: Date | null;
  metadata: Record<string, unknown>;
}

interface SearchParams {
  query?: string;
  type?: Observation['type'];
  projectId?: string;
  topicKey?: string;
  limit?: number;
  offset?: number;
}

interface SearchResult {
  observations: Observation[];
  total: number;
}

⚡ Practical Examples

Example 1: Complete Memory Workflow

import { MemoryEngine } from '@slorenzot/memento-core';

const memory = new MemoryEngine('./memory.db');

// Create session for tracking
const session = await memory.createSession({
  projectId: 'my-app',
  metadata: { agent: 'claude' }
});

// Save observations during work
await memory.createObservation({
  sessionId: session.id,
  title: 'Server configuration',
  content: 'Use Express.js with security middleware',
  type: 'decision',
  projectId: 'my-app',
  topicKey: 'backend'
});

await memory.createObservation({
  sessionId: session.id,
  title: 'Authentication bug',
  content: 'JWT not expiring correctly',
  type: 'bug',
  projectId: 'my-app',
  topicKey: 'security'
});

// Search for related decisions
const decisions = await memory.search({
  type: 'decision',
  projectId: 'my-app'
});

console.log('Decisions made:', decisions.observations);

// End session
await memory.endSession(session.id);

// Close connection
memory.close();

Example 2: Advanced Search

import { MemoryEngine } from '@slorenzot/memento-core';

const memory = new MemoryEngine('./memory.db');

// Complex search with multiple filters
const results = await memory.search({
  query: 'database architecture',
  type: 'decision',
  projectId: 'my-app',
  limit: 5,
  offset: 10
});

console.log(`Total results: ${results.total}`);
results.observations.forEach((obs, index) => {
  console.log(`${index + 1}. ${obs.title}`);
  console.log(`   ${obs.content.substring(0, 100)}...`);
  console.log(`   Type: ${obs.type} | Topic: ${obs.topicKey}`);
});

memory.close();

⚠️ Restrictive License

This package is under CC BY-NC-ND 4.0 License:

• ✅ Personal and educational use permitted
• ✅ Share with attribution to the author
• ❌ Commercial use NOT permitted
• ❌ Modifications or forks NOT permitted

Author: Soulberto Lorenzo ([email protected])

🔄 Dependencies

Main Dependencies

• zod - Schema validation
• nanoid - Unique ID generation

Peer Dependencies

• bun v1.0+ (recommended)
• node v20+ (compatible)

🛠️ Development

# Clone the project
git clone https://github.com/slorenzot/memento.git
cd memento/packages/core

# Install dependencies
bun install

# Development
bun run dev

# Build
bun run build

# Tests
bun test

📋 Changelog

[0.1.0] - 2024-04-04

• Added: Initial version of the memory engine
• Added: SQLite with FTS5 for full-text search
• Added: Session and observation management
• Added: Full TypeScript support

👤 Author

Soulberto Lorenzo

• GitHub: @slorenzot
• Email: [email protected]

📄 License

This package is licensed under Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International.

View Full License

⚠️ Important: This package has a restrictive license. Please respect the CC BY-NC-ND 4.0 license terms.

📖 Spanish version (Versión en español)