TypeScript Types Reference

Complete TypeScript type definitions for Memento. Use for type-safe integration and IDE autocompletion.

---

Core Types

MemoryEntry

Represents a single stored memory.

interface MemoryEntry {
  id: string;
  content: string;
  embedding?: number[];
  contentHash: string;
  parentId?: string;
  metadata: MemoryMetadata;
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier (UUID v4). Generated automatically on save. Example: "550e8400-e29b-41d4-a716-446655440000"
content	string	Yes	The actual memory text. Can be any length (chunked if >500 chars).
embedding	number[]	No	Vector embedding (384, 768, or 1536 dimensions depending on provider). Omitted in exports to save space.
contentHash	string	No	SHA256 hash of content for deduplication. Used to detect identical memories.
parentId	string	No	ID of parent entry if this is a chunk of a larger memory. Helps reconstruct full content.
metadata	MemoryMetadata	Yes	Rich metadata about the memory. See MemoryMetadata below.

Example

const entry: MemoryEntry = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  content: "Decided to use PostgreSQL for production database. Rationale: ACID guarantees, mature ecosystem, PostGIS support.",
  embedding: [0.123, -0.456, 0.789, ...],
  contentHash: "abc1234def5678...",
  parentId: undefined,
  metadata: {
    namespace: "myproject",
    tags: ["decision", "architecture"],
    timestamp: "2026-03-20T10:30:00Z",
    source: "explicit",
    summary: "PostgreSQL production decision"
  }
};

---

MemoryMetadata

Rich metadata about a memory entry.

interface MemoryMetadata {
  namespace: string;
  tags: MemoryTag[];
  timestamp: string;
  source: MemorySource;
  files?: string[];
  functions?: string[];
  sessionId?: string;
  summary?: string;
  relatedMemoryIds?: string[];
  container?: string;
  priority?: MemoryPriority;
  importance?: number;
  accessCount?: number;
  conversationId?: string;
}

Fields

Field	Type	Required	Description
namespace	string	Yes	Project namespace. Example: "myproject", "frontend", "auth-service". Used for scoping recalls.
tags	MemoryTag[]	Yes	Semantic tags. Can be built-in or custom. Example: ["decision", "architecture", "database"]
timestamp	string	Yes	ISO 8601 creation time. Example: "2026-03-20T10:30:00Z"
source	MemorySource	Yes	How the memory was created. Values: "explicit", "hook:post_tool_use", "hook:stop", "import"
files	string[]	No	File paths mentioned in the content. Extracted automatically. Example: ["src/auth.ts", "src/types.ts"]
functions	string[]	No	Function/method names mentioned. Example: ["handleLogin", "validateToken"]
sessionId	string	No	Session ID if entry created during a specific session. Used for session summaries.
summary	string	No	Brief summary of the content. Generated by summarization model if not provided. <100 chars.
relatedMemoryIds	string[]	No	IDs of related memories in the knowledge graph.
container	string	No	Container for multi-project/team scoping. Example: "team-backend", "personal". Defaults to namespace.
priority	MemoryPriority	No	Importance level: "low", "normal", "high". Default: "normal". Affects recall ranking.
importance	number	No	Computed importance score (0-1). Higher = more important. Used by ranking algorithms.
accessCount	number	No	Number of times this memory was accessed (recalled). Used for frequency-based ranking.
conversationId	string	No	Conversation ID if captured during a specific conversation.

Example

const metadata: MemoryMetadata = {
  namespace: "myproject",
  tags: ["decision", "architecture", "database"],
  timestamp: "2026-03-20T10:30:00Z",
  source: "explicit",
  files: ["src/database.ts", "migrations/001_schema.sql"],
  functions: ["createConnection", "migrate"],
  sessionId: "sess_2026-03-20-10am",
  summary: "Use PostgreSQL for production",
  container: "team-backend",
  priority: "high",
  importance: 0.95,
  accessCount: 12,
  conversationId: "conv_abc123"
};

---

MemoryTag

Type alias for semantic tags.

type MemoryTag = string;

Built-in tags:

const BUILT_IN_TAGS = [
  "conversation",   // Meeting notes, discussions
  "decision",       // Architecture decisions, choices
  "code",           // Code snippets, implementations
  "error",          // Bug reports, issues, fixes
  "architecture",   // System design, structure
  "config",         // Configuration, setup
  "dependency",     // Libraries, packages, versions
  "todo"            // Action items, reminders
] as const;

type BuiltInTag = typeof BUILT_IN_TAGS[number];

Usage

// Built-in tag
const tags1: MemoryTag[] = ["decision", "architecture"];

// Custom tags mixed with built-in
const tags2: MemoryTag[] = ["code", "performance", "optimization"];

// All custom
const tags3: MemoryTag[] = ["team-meeting", "q2-planning", "budget"];

---

MemorySource

Enum for how a memory was created.

type MemorySource = "explicit" | "hook:post_tool_use" | "hook:stop" | "import";

Value	Meaning	Example
"explicit"	Manually saved via memory_save tool	User called memory_save("...")
"hook:post_tool_use"	Auto-captured after tool execution	Automatic capture after using a tool
"hook:stop"	Auto-captured at conversation end	Automatic capture when session stops
"import"	Imported from external source	memory_import() or API import

Usage

const source: MemorySource = "explicit"; // User manually saved

// Don't set manually for auto-captured memories
// The system handles source automatically

---

MemoryPriority

Priority level affecting recall ranking.

type MemoryPriority = "low" | "normal" | "high";

Level	Usage	Recall Weight
"low"	Less important info, outdated notes	0.5x
"normal"	Regular memories, typical context	1.0x
"high"	Critical decisions, architecture	2.0x

Usage

const saveLow = {
  content: "Old debugging notes",
  priority: "low"
};

const saveHigh = {
  content: "Decision: Use microservices architecture",
  priority: "high"
};

---

MemoryResult

Result from search operations.

interface MemoryResult {
  entry: MemoryEntry;
  score: number;
}

Fields

Field	Type	Description
entry	MemoryEntry	The matched memory entry.
score	number	Relevance score (0.0-1.0). Higher = more relevant. Based on embedding cosine similarity.

Example

const result: MemoryResult = {
  entry: {
    id: "uuid-1",
    content: "Use PostgreSQL...",
    metadata: {...}
  },
  score: 0.9234  // Very high match
};

// Typical score ranges:
// 0.0-0.5: Poor match
// 0.5-0.7: Moderate match
// 0.7-0.85: Good match
// 0.85-1.0: Excellent match

---

MemoryRelation

Relationship between two memories.

interface MemoryRelation {
  sourceId: string;
  targetId: string;
  type: RelationType;
  strength: number;
  createdAt: string;
}

Fields

Field	Type	Description
sourceId	string	ID of the source memory.
targetId	string	ID of the target memory.
type	RelationType	Type of relationship. See RelationType below.
strength	number	Strength of relation (0.0-1.0). Higher = stronger connection.
createdAt	string	ISO 8601 timestamp when relation was created.

Example

const relation: MemoryRelation = {
  sourceId: "uuid-old-decision",
  targetId: "uuid-new-decision",
  type: "supersedes",
  strength: 0.92,
  createdAt: "2026-03-20T15:00:00Z"
};

---

RelationType

Types of relationships between memories.

type RelationType = "similar" | "supersedes" | "references" | "contradicts" | "elaborates";

Type	Meaning	Example
"similar"	Semantically similar memories	Two architectural patterns that are related
"supersedes"	New memory replaces old one	Updated decision supersedes old one
"references"	One memory mentions another	Implementation references the decision
"contradicts"	Conflicting information	Different approach contradicts another
"elaborates"	Adds detail to another memory	Implementation elaborates on the design

---

Options & Configuration Types

SaveOptions

Options for saving a memory.

interface SaveOptions {
  content: string;
  tags?: MemoryTag[];
  namespace?: string;
  global?: boolean;
  source?: MemorySource;
  files?: string[];
  functions?: string[];
  sessionId?: string;
  summary?: string;
  container?: string;
  priority?: MemoryPriority;
}

Fields

Field	Type	Required	Default	Description
content	string	Yes	—	Memory content to save.
tags	string[]	No	[]	Semantic tags.
namespace	string	No	auto-detected	Project namespace.
global	boolean	No	false	Save to global namespace.
source	MemorySource	No	"explicit"	How memory was created.
files	string[]	No	[]	Files mentioned.
functions	string[]	No	[]	Functions mentioned.
sessionId	string	No	—	Session ID if applicable.
summary	string	No	auto-generated	Brief summary.
container	string	No	namespace	Container for scoping.
priority	MemoryPriority	No	"normal"	Priority level.

Example

const opts: SaveOptions = {
  content: "Use PostgreSQL with Alembic migrations",
  tags: ["decision", "architecture", "database"],
  namespace: "myproject",
  priority: "high",
  summary: "PostgreSQL production database",
  sessionId: "sess_123"
};

const saved = await manager.save(opts);
// Returns: MemoryEntry[]

---

RecallOptions

Options for semantic recall.

interface RecallOptions {
  query: string;
  namespace?: string;
  tags?: MemoryTag[];
  limit?: number;
  after?: string;
  before?: string;
  container?: string;
  searchMode?: "vector" | "hybrid" | "keyword";
}

Fields

Field	Type	Required	Default	Description
query	string	Yes	—	Search query (natural language or keywords).
namespace	string	No	auto-detected	Project namespace to search.
tags	string[]	No	[]	Filter by tags (AND logic).
limit	number	No	10	Max results (1-100).
after	string	No	—	ISO date filter (entries created after).
before	string	No	—	ISO date filter (entries created before).
container	string	No	—	Filter by container.
searchMode	string	No	"vector"	Search strategy: vector, keyword, or hybrid.

Example

const opts: RecallOptions = {
  query: "authentication and OAuth",
  namespace: "myproject",
  tags: ["decision", "architecture"],
  limit: 10,
  searchMode: "hybrid"
};

const results = await manager.recall(opts);
// Returns: MemoryResult[]

---

ListOptions

Options for listing memories.

interface ListOptions {
  namespace?: string;
  tags?: MemoryTag[];
  limit?: number;
  offset?: number;
  container?: string;
}

Example

const opts: ListOptions = {
  namespace: "myproject",
  tags: ["decision"],
  limit: 20,
  offset: 0
};

const entries = await manager.list(opts);
// Returns: MemoryEntry[]

---

Storage Interface Types

VectorStore Interface

Interface that all storage backends implement.

interface VectorStore {
  initialize(): Promise<void>;
  upsert(entry: MemoryEntry): Promise<void>;
  search(queryEmbedding: number[], filters: SearchFilters): Promise<MemoryResult[]>;
  delete(id: string): Promise<boolean>;
  list(filters: ListFilters): Promise<MemoryEntry[]>;
  count(namespace?: string): Promise<number>;
  close(): Promise<void>;
}

Methods

Method	Signature	Description
initialize()	() => Promise<void>	Initialize storage backend. Called once on startup.
upsert()	(entry: MemoryEntry) => Promise<void>	Save or update an entry.
search()	(embedding: number[], filters: SearchFilters) => Promise<MemoryResult[]>	Search by embedding vector.
delete()	(id: string) => Promise<boolean>	Delete entry by ID. Returns true if deleted, false if not found.
list()	(filters: ListFilters) => Promise<MemoryEntry[]>	List entries with filtering.
count()	(namespace?: string) => Promise<number>	Count entries in namespace.
close()	() => Promise<void>	Close connections and cleanup.

---

SearchFilters

Filters for vector search operations.

interface SearchFilters {
  namespace?: string;
  tags?: string[];
  after?: string;
  before?: string;
  limit: number;
  searchMode?: SearchMode;
  query?: string;
}

type SearchMode = "vector" | "hybrid" | "keyword";

---

ListFilters

Filters for list operations.

interface ListFilters {
  namespace?: string;
  tags?: string[];
  limit: number;
  offset: number;
}

---

Embedding Provider Interface

EmbeddingProvider Interface

interface EmbeddingProvider {
  readonly dimensions: number;
  readonly modelName: string;
  embed(text: string): Promise<number[]>;
  embedBatch(texts: string[]): Promise<number[][]>;
}

Properties

Property	Type	Description
dimensions	number	Vector dimension count (384, 768, 1536).
modelName	string	Model identifier (e.g., "Xenova/all-MiniLM-L6-v2").

Methods

Method	Signature	Description
embed()	(text: string) => Promise<number[]>	Embed single text to vector.
embedBatch()	(texts: string[]) => Promise<number[][]>	Embed multiple texts efficiently.

Example

const provider: EmbeddingProvider = {
  dimensions: 384,
  modelName: "Xenova/all-MiniLM-L6-v2",
  embed: async (text) => {
    // Return [0.123, -0.456, 0.789, ...]
  },
  embedBatch: async (texts) => {
    // Return [[...], [...], ...]
  }
};

const vector = await provider.embed("Hello world");
// vector.length === 384

---

Constants

Global Constants

// Default namespace for global memories
export const GLOBAL_NAMESPACE = "__global__";

// Default and max limits
export const DEFAULT_LIMIT = 10;
export const MAX_LIMIT = 100;

// Built-in tags
export const BUILT_IN_TAGS = [
  "conversation",
  "decision",
  "code",
  "error",
  "architecture",
  "config",
  "dependency",
  "todo",
] as const;

// Signal keywords for auto-tagging
export const SIGNAL_KEYWORDS = [
  "remember",
  "important",
  "decision",
  "architecture",
  "bug",
  "fix",
  "never",
  "always",
  "convention",
  "pattern",
  "rule",
  "workaround",
  "deprecated",
  "migrate",
] as const;

---

Config Types

MementoConfig

Main configuration interface.

interface MementoConfig {
  store: StoreConfig;
  embeddings: EmbeddingsConfig;
  capture: CaptureConfig;
  memory: MemoryConfig;
  dataDir: string;
}

interface StoreConfig {
  type: "local" | "chromadb" | "neo4j";
  localPath: string;
  chromaPath: string;
  neo4jUrl?: string;
  neo4jUser?: string;
  neo4jPassword?: string;
}

interface EmbeddingsConfig {
  provider: "local" | "openai" | "gemini";
  model: string;
  dimensions: number;
  openaiApiKey?: string;
  geminiApiKey?: string;
}

interface CaptureConfig {
  autoCapture: boolean;
  hooks: ("post_tool_use" | "stop")[];
  redactSecrets: boolean;
  maxContentLength: number;
  queueFlushIntervalMs: number;
}

interface MemoryConfig {
  defaultNamespace: string;
  defaultLimit: number;
  maxLimit: number;
  deduplicationThreshold: number;
  chunkSize: number;
  chunkOverlap: number;
}

---

Usage Examples

Importing Types

import type {
  MemoryEntry,
  MemoryMetadata,
  MemoryResult,
  MemorySource,
  MemoryTag,
  SaveOptions,
  RecallOptions,
  VectorStore,
  EmbeddingProvider,
  MementoConfig
} from "memento-memory";

Type-Safe Operations

import { MemoryManager } from "memento-memory";
import type { SaveOptions, MemoryResult } from "memento-memory";

const manager = new MemoryManager();

// Type-safe save
const saveOpts: SaveOptions = {
  content: "Important decision",
  tags: ["decision", "architecture"],
  priority: "high"
};

const saved = await manager.save(saveOpts);
// saved: MemoryEntry[]

// Type-safe recall
const results: MemoryResult[] = await manager.recall({
  query: "architecture decisions",
  limit: 10
});

// Type-safe processing
results.forEach((result) => {
  console.log(result.entry.content);
  console.log(result.score);
});

---

Utility Types

Extracting Fields

// Get just the metadata type
type Metadata = MemoryEntry["metadata"];

// Get tag values
type TagValue = MemoryTag;

// Get source values
type SourceValue = MemorySource;

---

Notes

• All timestamps use ISO 8601 format with timezone (YYYY-MM-DDTHH:mm:ssZ)
• UUIDs are v4 format (random 128-bit)
• Vectors are always Float32Array or number[]
• All async operations may throw errors (caller responsible for error handling)
• Metadata is flexible (can add custom fields)
• Tags are case-sensitive strings