Engram Trace

Autonomous memory intelligence for AI agents.

Engram Trace gives any AI agent persistent, self-curating memory in a single .engram file. It automatically decides what to remember from conversations, consolidates old memories, removes duplicates, and provides semantic recall -- all without manual memory management.

Built on the Engram neural memory format.

The Problem

AI agents lose context between sessions. Current solutions require manual memory management (markdown files, vector databases, external services) that doesn't scale and breaks when the agent restarts.

The Solution

One file. One import. Zero maintenance.

import { EngramTrace } from '@terronex/engram-trace';

const memory = new EngramTrace({ file: './agent.engram' });
await memory.init();

// Agent now has persistent, self-curating memory

Quick Start

npm install @terronex/engram-trace

import { EngramTrace } from '@terronex/engram-trace';

// 1. Initialize
const memory = new EngramTrace({
  file: './my-agent.engram',
  debug: true,
});
await memory.init();

// 2. Bootstrap session context (replaces "read MEMORY.md")
const ctx = await memory.bootstrap();
console.log(ctx.identity);    // Who am I, who is my user
console.log(ctx.priorities);  // Active projects, current focus
console.log(ctx.decisions);   // Recent decisions, open blockers
console.log(ctx.preferences); // User preferences, communication style

// 3. Process conversation turns (auto-classifies and stores)
const result = await memory.process(
  'We decided to use MIT license for everything',
  'Got it. MIT license applied across all repos.'
);
console.log(result);
// { shouldRemember: true, importance: 0.85, reason: 'contains decision', suggestedTags: ['decision'] }

// 4. Explicit recall
const memories = await memory.recall('what license do we use');
// Returns top matches ranked by relevance + recency + importance

// 5. Explicit remember
await memory.remember('Deploy target is Cloudflare Pages', {
  importance: 0.7,
  tags: ['infrastructure'],
});

// 6. Cleanup
await memory.close();

How It Works

Auto-Remember

Every conversation turn is classified by importance using heuristic pattern matching:

Signal	Importance	Example
Explicit command	0.95	"Remember this", "Note that"
Decision	0.85	"We decided to use MIT license"
Lesson learned	0.85	"The problem was msgpackr corrupting Float32Array"
Preference	0.80	"I prefer concise responses"
Identity info	0.80	"My name is Jason, I work at Terronex"
Factual data	0.60	API keys, URLs, version numbers
Technical discussion	0.50	Architecture, design, schemas
Greeting/filler	0.00	"ok", "thanks", "nice" (skipped)

Memories are deduplicated before storage. If a new memory is >92% similar to an existing one, it's skipped.

Auto-Curate (Consolidation)

Runs automatically every 100 writes or every 6 hours (configurable):

1. Decay -- memories age through tiers based on time and access frequency

   • HOT (0-7 days) -> WARM (7-30 days) -> COLD (30-365 days) -> ARCHIVE (>365 days)
   • Frequently accessed memories stay hotter longer
   • High-importance memories decay slower

2. Deduplicate -- remove near-identical memories (cosine similarity >0.92)

3. Cluster -- group similar memories by embedding proximity

4. Summarize -- collapse clusters into condensed memories (requires LLM)

5. Archive -- truncate old archive-tier content to save space

Semantic Recall

Recall is tier-aware: HOT memories get a slight relevance boost, ARCHIVE memories are deprioritized. Access counts update on every recall, which feeds back into the decay algorithm.

const results = await memory.recall('deployment infrastructure', {
  limit: 5,
  minScore: 0.2,
  tiers: ['hot', 'warm'],  // Only recent memories
  tags: ['infrastructure'], // Filter by tag
});

Configuration

const memory = new EngramTrace({
  // Required
  file: './agent.engram',

  // Embedding provider (default: local, zero-config)
  embedder: {
    provider: 'local',                    // 'local' | 'ollama' | 'openai'
    model: 'Xenova/all-MiniLM-L6-v2',    // Default model
  },

  // LLM for consolidation summaries (optional)
  llm: {
    provider: 'ollama',                   // 'ollama' | 'anthropic' | 'openai'
    model: 'llama3.1:8b',
  },

  // Auto-remember behavior
  autoRemember: {
    heuristic: true,       // Use pattern-based classifier
    minImportance: 0.3,    // Minimum score to store
    defaultTags: ['auto'], // Tags applied to all auto-memories
  },

  // Auto-consolidation behavior
  autoConsolidate: {
    everyNWrites: 100,          // Consolidate every N writes
    intervalMs: 6 * 3600000,   // Or every 6 hours
    minClusterSize: 3,          // Min memories to form a cluster
    clusterThreshold: 0.78,     // Similarity threshold for clustering
    hotDays: 7,                 // Days before HOT -> WARM
    warmDays: 30,               // Days before WARM -> COLD
    coldDays: 365,              // Days before COLD -> ARCHIVE
  },

  // Deduplication threshold (0-1)
  deduplicateThreshold: 0.92,

  // Hard limit before forced consolidation
  maxMemories: 10000,

  // Debug logging
  debug: false,
});

Minimal Config (Zero Config)

// This is all you need. Everything else has sensible defaults.
const memory = new EngramTrace({ file: './agent.engram' });

With Ollama (Free, Private, Local)

const memory = new EngramTrace({
  file: './agent.engram',
  llm: { provider: 'ollama', model: 'llama3.1:8b' },
});

With Claude (Higher Quality Consolidation)

const memory = new EngramTrace({
  file: './agent.engram',
  llm: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
});

API Reference

new EngramTrace(config)

Create a new trace instance. Does not load the file yet.

.init(): Promise<void>

Load existing memories from the .engram file (or start fresh). Must be called before any other method.

.bootstrap(): Promise<BootstrapContext>

Run 4 broad recall queries to build session context. Returns:

• identity -- who the agent is, who the user is
• priorities -- active projects, current focus
• decisions -- recent decisions, open blockers
• preferences -- user preferences, communication style
• raw -- the full RecallResult arrays

.process(userMessage, assistantResponse): Promise<ClassificationResult>

Classify a conversation turn and auto-store if worthy. Returns:

• shouldRemember -- whether it was stored
• importance -- score (0-1)
• reason -- why it was classified this way
• suggestedTags -- auto-detected tags

.remember(content, options?): Promise<Memory>

Explicitly store a memory. Options:

• importance -- 0-1, default 0.5
• tags -- string array
• source -- source identifier
• metadata -- arbitrary key-value data

.recall(query, options?): Promise<RecallResult[]>

Semantic search. Options:

• limit -- max results (default 8)
• minScore -- minimum similarity (default 0.15)
• tiers -- filter by memory tier
• tags -- filter by tags
• decayBoost -- apply temporal boosting (default true)

.forget(query, threshold?): Promise<number>

Remove memories matching a query above the similarity threshold. Returns count removed. Useful for corrections and GDPR compliance.

.consolidate(): Promise<ConsolidationReport>

Run consolidation manually. Returns a detailed report of what changed.

.stats(): TraceStats

Get current state: memory counts by tier, file size, last consolidation, etc.

.export(): Array<...>

Export all memories as JSON (embeddings excluded for readability).

.close(): Promise<void>

Save to disk and clean up timers. Call this on shutdown.

Architecture

                   Your Agent / Bot
                        |
                   EngramTrace
                   /    |    \
          Classifier  Store  Consolidator
              |         |         |
          Heuristic  .engram   Cluster
          Patterns    File     Summarize
              |         |      Decay
          Embedder   @terronex  LLM
          (local)    /engram   (optional)

No external services required. Embeddings run locally via @xenova/transformers. The LLM is optional (only used for consolidation summaries). Everything persists in a single portable .engram file.

Integration Examples

OpenClaw / Clawdbot

// In agent initialization
const memory = new EngramTrace({ file: '~/.openclaw/agents/main/memory.engram' });
await memory.init();
const ctx = await memory.bootstrap();
systemPrompt += ctx.identity + ctx.preferences;

// In message handler
async function onMessage(user, assistant) {
  await memory.process(user, assistant);
}

// In heartbeat
async function onHeartbeat() {
  await memory.consolidate();
}

Discord Bot

client.on('messageCreate', async (msg) => {
  const response = await generateResponse(msg.content);
  await memory.process(msg.content, response);
  msg.reply(response);
});

Express API

app.post('/chat', async (req, res) => {
  const ctx = await memory.bootstrap();
  const response = await llm.chat(req.body.message, { context: ctx });
  await memory.process(req.body.message, response);
  res.json({ response });
});

Performance

Benchmarked on WSL2 / Intel CPU / RTX 4070 Super (GPU used only for Ollama LLM, not embeddings):

Operation	Latency	Notes
Embedding (local)	2.5ms	MiniLM-L6-v2, CPU
Recall (4K memories)	4.6ms	Cosine similarity + tier boost
Recall (275 memories)	3.8ms	Sub-linear scaling
Process (classify + embed + store)	~8ms	Heuristic classifier
Consolidation (4K memories)	Varies	Depends on cluster count + LLM
Bootstrap (4 queries)	~16ms	Parallel recall
File load (25 MB)	~1100ms	One-time at init

File Format

Engram Trace stores everything in a single .engram file using the Engram neural memory format. Each memory is a node containing:

• Content text
• 384-dimensional embedding vector (MiniLM-L6-v2)
• Metadata (tier, importance, tags, timestamps, access count)

The file is portable, version-controllable, and human-inspectable (via engram CLI tools).

License

MIT -- Terronex 2026

---

Trace vs Trace Lite

This package (@terronex/engram-trace) is designed for autonomous AI agents that run continuously and manage their own memory lifecycle. It includes background consolidation timers, auto-remember heuristics, and built-in embedding/LLM providers.

For applications that manage memory explicitly (interactive tools, teaching systems, CLIs), see @terronex/engram-trace-lite -- a stateless, pure-function consolidation library with zero background processes.

	Trace (this package)	Trace Lite
Architecture	Stateful class with timers	Stateless pure functions
Agent loop	Built-in auto-remember, auto-consolidate	None -- caller triggers consolidation
LLM	Optional (summarization + auto-importance)	Optional (summarization only)
Embedding	Built-in provider support	Bring your own
Background work	Interval-based consolidation	None
Recall	Built-in with tier filtering	Not included (use @terronex/engram)
Size	~1,700 lines	~300 lines
Use case	Rex, autonomous agents, daemons	Allo, teaching systems, custom apps

Disclaimer

This software is provided as-is under the MIT license. It is under active development and has not undergone a third-party security audit. The encryption implementation (AES-256-GCM with argon2id/PBKDF2) has not been independently verified.

Do not use this software as the sole protection for sensitive data without your own due diligence. The authors and Terronex are not liable for data loss, security breaches, or any damages arising from the use of this software. See LICENSE for full terms.