audrey 0.5.1 → 0.8.0

package/README.md

@@ -2,7 +2,6 @@
 
 Biological memory architecture for AI agents. Gives agents cognitive memory that decays, consolidates, self-validates, and learns from experience — not just a database.
 
-
 ## Why Audrey Exists
 
 Every AI memory tool today (Mem0, Zep, LangChain Memory) is a filing cabinet. Store stuff, retrieve stuff. None of them do what biological memory actually does:
@@ -46,7 +45,7 @@ npx audrey status
 npx audrey uninstall
 ```
 
-Every Claude Code session now has 7 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`, `memory_export`, `memory_import`.
+Every Claude Code session now has 9 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`, `memory_export`, `memory_import`, `memory_forget`, `memory_decay`.
 
 ### SDK in Your Code
 
@@ -79,14 +78,26 @@ await brain.encode({
 const memories = await brain.recall('stripe rate limits', { limit: 5 });
 // Returns: [{ content, type, confidence, score, ... }]
 
-// 4. Consolidate episodes into principles (the "sleep" cycle)
+// 4. Filtered recall — by tag, source, or date range
+const recent = await brain.recall('stripe', {
+  tags: ['rate-limit'],
+  sources: ['direct-observation'],
+  after: '2026-02-01T00:00:00Z',
+});
+
+// 5. Consolidate episodes into principles (the "sleep" cycle)
 await brain.consolidate();
 
-// 5. Check brain health
+// 6. Forget something
+brain.forget(memoryId);                                 // soft-delete
+brain.forget(memoryId, { purge: true });                // hard-delete
+await brain.forgetByQuery('old API endpoint', { minSimilarity: 0.9 });
+
+// 7. Check brain health
 const stats = brain.introspect();
 // { episodic: 47, semantic: 12, procedural: 3, dormant: 8, ... }
 
-// 6. Clean up
+// 8. Clean up
 brain.close();
 ```
 
@@ -219,6 +230,16 @@ Context-dependent truths are modeled explicitly:
 
 New high-confidence evidence can reopen resolved disputes.
 
+### Forget and Purge
+
+Memories can be explicitly forgotten — by ID or by semantic query:
+
+**Soft-delete** (default) — Marks the memory as forgotten/superseded and removes its vector index. The record stays in the database but is excluded from recall. Reversible via direct database access.
+
+**Hard-delete** (`purge: true`) — Permanently removes the memory from both the main table and the vector index. Irreversible.
+
+**Bulk purge** — Removes all forgotten, dormant, superseded, and rolled-back memories in one operation. Useful for GDPR compliance or storage cleanup.
+
 ### Rollback
 
 Bad consolidation? Undo it:
@@ -268,20 +289,38 @@ const id = await brain.encode({
 
 Episodes are **immutable**. Corrections create new records with `supersedes` links. The original is preserved.
 
+### `brain.encodeBatch(paramsList)` → `Promise<string[]>`
+
+Encode multiple episodes in one call. Same params as `encode()`, but as an array.
+
+```js
+const ids = await brain.encodeBatch([
+  { content: 'Stripe returned 429', source: 'direct-observation' },
+  { content: 'Redis timed out', source: 'tool-result' },
+  { content: 'User reports slow checkout', source: 'told-by-user' },
+]);
+```
+
 ### `brain.recall(query, options)` → `Promise<Memory[]>`
 
 Retrieve memories ranked by `similarity * confidence`.
 
 ```js
 const memories = await brain.recall('stripe rate limits', {
-  minConfidence: 0.5,            // Filter below this confidence
-  types: ['semantic'],           // Filter by memory type
-  limit: 5,                     // Max results
-  includeProvenance: true,       // Include evidence chains
-  includeDormant: false,         // Include dormant memories
+  limit: 5,                       // Max results (default 10)
+  minConfidence: 0.5,             // Filter below this confidence
+  types: ['semantic'],            // Filter by memory type
+  includeProvenance: true,        // Include evidence chains
+  includeDormant: false,          // Include dormant memories
+  tags: ['rate-limit'],           // Only episodic memories with these tags
+  sources: ['direct-observation'], // Only episodic memories from these sources
+  after: '2026-02-01T00:00:00Z', // Only memories created after this date
+  before: '2026-03-01T00:00:00Z', // Only memories created before this date
 });
 ```
 
+Tag and source filters only apply to episodic memories (semantic and procedural memories don't have tags or sources). Date filters apply to all memory types.
+
 Each result:
 
 ```js
@@ -304,21 +343,9 @@ Each result:
 
 Retrieval automatically reinforces matched memories (boosts confidence, resets decay clock).
 
-### `brain.encodeBatch(paramsList)` → `Promise<string[]>`
-
-Encode multiple episodes in one call. Same params as `encode()`, but as an array.
-
-```js
-const ids = await brain.encodeBatch([
-  { content: 'Stripe returned 429', source: 'direct-observation' },
-  { content: 'Redis timed out', source: 'tool-result' },
-  { content: 'User reports slow checkout', source: 'told-by-user' },
-]);
-```
-
 ### `brain.recallStream(query, options)` → `AsyncGenerator<Memory>`
 
-Streaming version of `recall()`. Yields results one at a time. Supports early `break`.
+Streaming version of `recall()`. Yields results one at a time. Supports early `break`. Same options as `recall()`.
 
 ```js
 for await (const memory of brain.recallStream('stripe issues', { limit: 10 })) {
@@ -327,6 +354,37 @@ for await (const memory of brain.recallStream('stripe issues', { limit: 10 })) {
 }
 ```
 
+### `brain.forget(id, options)` → `ForgetResult`
+
+Forget a memory by ID. Works on any memory type (episodic, semantic, procedural).
+
+```js
+brain.forget(memoryId);                       // soft-delete
+brain.forget(memoryId, { purge: true });      // hard-delete (permanent)
+// { id, type: 'episodic', purged: false }
+```
+
+### `brain.forgetByQuery(query, options)` → `Promise<ForgetResult | null>`
+
+Find the closest matching memory by semantic search and forget it. Searches all three memory types, picks the best match.
+
+```js
+const result = await brain.forgetByQuery('old API endpoint', {
+  minSimilarity: 0.9,    // Threshold for match (default 0.9)
+  purge: false,          // Hard-delete? (default false)
+});
+// null if no match above threshold
+```
+
+### `brain.purge()` → `PurgeCounts`
+
+Bulk hard-delete all dead memories: forgotten episodes, dormant/superseded/rolled-back semantics and procedures.
+
+```js
+const counts = brain.purge();
+// { episodes: 12, semantics: 3, procedures: 0 }
+```
+
 ### `brain.consolidate(options)` → `Promise<ConsolidationResult>`
 
 Run the consolidation engine manually.
@@ -389,6 +447,15 @@ brain.introspect();
 
 Full audit trail of all consolidation runs.
 
+### `brain.export()` / `brain.import(snapshot)`
+
+Export all memories as a JSON snapshot, or import from one.
+
+```js
+const snapshot = brain.export();   // { version, episodes, semantics, procedures, ... }
+await brain.import(snapshot);      // Re-embeds everything with current provider
+```
+
 ### Events
 
 ```js
@@ -398,6 +465,8 @@ brain.on('contradiction', ({ episodeId, contradictionId, semanticId, resolution
 brain.on('consolidation', ({ runId, principlesExtracted }) => { ... });
 brain.on('decay', ({ totalEvaluated, transitionedToDormant }) => { ... });
 brain.on('rollback', ({ runId, rolledBackMemories }) => { ... });
+brain.on('forget', ({ id, type, purged }) => { ... });
+brain.on('purge', ({ episodes, semantics, procedures }) => { ... });
 brain.on('migration', ({ episodes, semantics, procedures }) => { ... });
 brain.on('error', (err) => { ... });
 ```
@@ -410,7 +479,7 @@ Close the database connection.
 
 ```
 audrey-data/
-  audrey.db          ← Single SQLite file. WAL mode. That's your brain.
+  audrey.db          <- Single SQLite file. WAL mode. That's your brain.
 ```
 
 ```
@@ -418,15 +487,16 @@ src/
   audrey.js          Main class. EventEmitter. Public API surface.
   causal.js          Causal graph management. LLM-powered mechanism articulation.
   confidence.js      Compositional confidence formula. Pure math.
-  consolidate.js     "Sleep" cycle. KNN clustering → LLM extraction → promote.
+  consolidate.js     "Sleep" cycle. KNN clustering -> LLM extraction -> promote.
   db.js              SQLite + sqlite-vec. Schema, vec0 tables, migrations.
   decay.js           Ebbinghaus forgetting curves.
   embedding.js       Pluggable providers (Mock, OpenAI). Batch embedding.
   encode.js          Immutable episodic memory creation + vec0 writes.
+  forget.js          Soft-delete, hard-delete, query-based forget, bulk purge.
   introspect.js      Health dashboard queries.
   llm.js             Pluggable LLM providers (Mock, Anthropic, OpenAI).
   prompts.js         Structured prompt templates for LLM operations.
-  recall.js          KNN retrieval + confidence scoring + async streaming.
+  recall.js          KNN retrieval + confidence scoring + filtered recall + streaming.
   rollback.js        Undo consolidation runs.
   utils.js           Date math, safe JSON parse.
   validate.js        KNN validation + LLM contradiction detection.
@@ -437,7 +507,7 @@ src/
   index.js           Barrel export.
 
 mcp-server/
-  index.js           MCP tool server (7 tools, stdio transport) + CLI subcommands.
+  index.js           MCP tool server (9 tools, stdio transport) + CLI subcommands.
   config.js          Shared config (env var parsing, install arg builder).
 ```
 
@@ -461,7 +531,7 @@ All mutations use SQLite transactions. CHECK constraints enforce valid states an
 ## Running Tests
 
 ```bash
-npm test          # 243 tests across 22 files
+npm test          # 278 tests across 23 files
 npm run test:watch
 ```
 
@@ -471,115 +541,60 @@ npm run test:watch
 node examples/stripe-demo.js
 ```
 
-Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate into principle → recall proactively.
+Demonstrates the full pipeline: encode 3 rate-limit observations, consolidate into principle, recall proactively.
 
 ---
 
-## Roadmap
+## Changelog
 
-### v0.1.0 — Foundation
+### v0.6.0 — Filtered Recall + Forget (current)
 
-- [x] Immutable episodic memory with append-only records
-- [x] Compositional confidence formula (source + evidence + recency + retrieval)
-- [x] Ebbinghaus-inspired forgetting curves with configurable half-lives
-- [x] Dormancy transitions for low-confidence memories
-- [x] Confidence-weighted recall across episodic/semantic/procedural types
-- [x] Provenance chains (which episodes contributed to which principles)
-- [x] Retrieval reinforcement (frequently accessed memories resist decay)
-- [x] Consolidation engine with clustering and principle extraction
-- [x] Idempotent consolidation with checkpoint cursors
-- [x] Full consolidation audit trail (input/output IDs per run)
-- [x] Consolidation rollback (undo bad runs, restore episodes)
-- [x] Contradiction lifecycle (open/resolved/context_dependent/reopened)
-- [x] Circular self-confirmation defense (model-generated cap at 0.6)
-- [x] Source type diversity tracking on semantic memories
-- [x] Supersedes links for correcting episodic memories
-- [x] Pluggable embedding providers (Mock for tests, OpenAI for production)
-- [x] Causal context storage (trigger/consequence per episode)
-- [x] Introspection API (memory counts, contradiction stats, consolidation history)
-- [x] EventEmitter lifecycle hooks (encode, reinforcement, consolidation, decay, rollback, error)
-- [x] SQLite with WAL mode, CHECK constraints, indexes, foreign keys
-- [x] Transaction safety on all multi-step mutations
-- [x] Input validation on public API (content, salience, tags, source)
-- [x] Shared utility extraction (cosine similarity, date math, safe JSON parse)
-- [x] 104 tests across 12 test files
-- [x] Proof-of-concept demo (Stripe rate limit scenario)
+- Filtered recall: tag, source, and date-range filters on `recall()` and `recallStream()`
+- `forget()` — soft-delete any memory by ID
+- `forgetByQuery()` — find closest match by semantic search and forget it
+- `purge()` — bulk hard-delete all forgotten/dormant/superseded memories
+- `memory_forget` and `memory_decay` MCP tools (9 tools total)
+- 278 tests across 23 files
 
-### v0.2.0 — LLM Integration
+### v0.5.0 — Feature Depth
 
-- [x] LLM-powered principle extraction (replace callback with Anthropic/OpenAI calls)
-- [x] LLM-based contradiction detection during validation
-- [x] Causal mechanism articulation via LLM (not just trigger/consequence)
-- [x] Spurious correlation detection (require mechanistic explanation for causal links)
-- [x] Context-dependent truth resolution via LLM
-- [x] Configurable LLM provider for consolidation (Mock, Anthropic, OpenAI)
-- [x] Structured prompt templates for all LLM operations
-- [x] 142 tests across 15 test files
+- Configurable confidence weights and decay rates per instance
+- Memory export/import (JSON snapshots with re-embedding)
+- `memory_export` and `memory_import` MCP tools
+- Auto-consolidation scheduling
+- Adaptive consolidation parameter suggestions
+- 243 tests across 22 files
+
+### v0.3.1 — MCP Server
+
+- MCP tool server via `@modelcontextprotocol/sdk` with stdio transport
+- One-command install: `npx audrey install` (auto-detects API keys)
+- CLI subcommands: `install`, `uninstall`, `status`
+- JSDoc type annotations on all public exports
+- Published to npm
+- 194 tests across 17 files
 
 ### v0.3.0 — Vector Performance
 
-- [x] sqlite-vec native vector indexing (vec0 virtual tables with cosine distance)
-- [x] KNN queries for recall, validation, and consolidation clustering (all vector math in C)
-- [x] SQL-native metadata filtering in KNN (state, source, consolidated)
-- [x] Batch encoding API (`encodeBatch` — encode N episodes in one call)
-- [x] Streaming recall with async generators (`recallStream`)
-- [x] Dimension configuration and mismatch validation
-- [x] Automatic migration from v0.2.0 embedding BLOBs to vec0 tables
-- [x] 168 tests across 16 test files
-
-### v0.3.1 — MCP Server + JSDoc Types
-
-- [x] MCP tool server via `@modelcontextprotocol/sdk` with stdio transport
-- [x] 5 tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`
-- [x] Configuration via environment variables (data dir, embedding provider, LLM provider)
-- [x] One-command install: `npx audrey install` (auto-detects API keys)
-- [x] CLI subcommands: `install`, `uninstall`, `status`
-- [x] JSDoc type annotations on all public exports (16 source files)
-- [x] Published to npm with proper package metadata
-- [x] 194 tests across 17 test files
-
-### v0.5.0 — Feature Depth (current)
-
-- [x] Configurable confidence weights per Audrey instance
-- [x] Configurable decay rates (half-lives) per Audrey instance
-- [x] Confidence config wired through constructor to recall and decay
-- [x] Memory export (JSON snapshot of all tables, no raw embeddings)
-- [x] Memory import with automatic re-embedding via current provider
-- [x] `memory_export` and `memory_import` MCP tools (7 tools total)
-- [x] Auto-consolidation scheduling (`startAutoConsolidate` / `stopAutoConsolidate`)
-- [x] Consolidation metrics tracking (per-run params and results)
-- [x] Adaptive consolidation parameter suggestions based on historical yield
-- [x] 243 tests across 22 test files
-
-### v0.4.0 — Type Safety & Developer Experience
-
-- [ ] Full TypeScript conversion with strict mode
-- [ ] Published type declarations (.d.ts)
-- [ ] Schema versioning and migration system
-- [ ] Structured logging (optional, pluggable)
-
-### v0.4.5 — Embedding Migration (deferred from v0.3.0)
-
-- [ ] Embedding migration pipeline (re-embed when models change)
-- [ ] Re-consolidation queue (re-run consolidation with new embedding model)
-
-### v0.6.0 — Scale
-
-- [ ] pgvector adapter for PostgreSQL backend
-- [ ] Redis adapter for distributed caching
-- [ ] Connection pooling for concurrent agent access
-- [ ] Pagination on recall queries (cursor-based)
-- [ ] Benchmarks: encode throughput, recall latency at 10k/100k/1M memories
-
-### v1.0.0 — Production Ready
-
-- [ ] Comprehensive error handling at all boundaries
-- [ ] Rate limiting on embedding API calls
-- [ ] Memory usage profiling and optimization
-- [ ] Security audit (injection, data isolation)
-- [ ] Cross-agent knowledge sharing protocol (Hivemind)
-- [ ] Documentation site
-- [ ] Integration guides (LangChain, CrewAI, Claude Code, custom agents)
+- sqlite-vec native vector indexing (vec0 virtual tables with cosine distance)
+- KNN queries for recall, validation, and consolidation clustering
+- Batch encoding API and streaming recall with async generators
+- Dimension configuration and automatic migration from v0.2.0
+- 168 tests across 16 files
+
+### v0.2.0 — LLM Integration
+
+- LLM-powered principle extraction, contradiction detection, causal articulation
+- Context-dependent truth resolution
+- Configurable LLM providers (Mock, Anthropic, OpenAI)
+- 142 tests across 15 files
+
+### v0.1.0 — Foundation
+
+- Immutable episodic memory, compositional confidence, Ebbinghaus forgetting curves
+- Consolidation engine, contradiction lifecycle, rollback
+- Circular self-confirmation defense, causal context, introspection
+- 104 tests across 12 files
 
 ## Design Decisions
 
@@ -591,7 +606,7 @@ Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate
 
 **Why model-generated cap at 0.6?** Prevents the most dangerous exploit in AI memory: circular self-confirmation where an agent's own inferences bootstrap themselves into high-confidence "facts" through repeated retrieval.
 
-**Why no TypeScript yet?** Prototyping speed. TypeScript conversion is on the roadmap for v0.4.0. The pure-math modules (`confidence.js`, `utils.js`) are already type-safe in practice.
+**Why soft-delete by default?** Hard-deletes are irreversible. Soft-delete preserves data integrity and audit trails while excluding the memory from recall. Use `purge: true` or `brain.purge()` when you need permanent removal (GDPR, storage cleanup).
 
 ## License
 

package/mcp-server/config.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const VERSION = '0.5.1';
+export const VERSION = '0.8.0';
 export const SERVER_NAME = 'audrey-memory';
 export const DEFAULT_DATA_DIR = join(homedir(), '.audrey', 'data');
 

package/mcp-server/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -65,7 +65,7 @@ function install() {
   console.log(`
 Audrey registered as "${SERVER_NAME}" with Claude Code.
 
-7 tools available in every session:
+9 tools available in every session:
   memory_encode        — Store observations, facts, preferences
   memory_recall        — Search memories by semantic similarity
   memory_consolidate   — Extract principles from accumulated episodes
@@ -73,6 +73,8 @@ Audrey registered as "${SERVER_NAME}" with Claude Code.
   memory_resolve_truth — Resolve contradictions between claims
   memory_export        — Export all memories as JSON snapshot
   memory_import        — Import a snapshot into a fresh database
+  memory_forget        — Forget a specific memory by ID or query
+  memory_decay         — Apply forgetting curves, transition low-confidence to dormant
 
 Data stored in: ${DEFAULT_DATA_DIR}
 Verify: claude mcp list
@@ -161,10 +163,11 @@ async function main() {
       source: z.enum(VALID_SOURCES).describe('Source type of the memory'),
       tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
       salience: z.number().min(0).max(1).optional().describe('Importance weight 0-1'),
+      context: z.record(z.string()).optional().describe('Situational context as key-value pairs (e.g., {task: "debugging", domain: "payments"})'),
     },
-    async ({ content, source, tags, salience }) => {
+    async ({ content, source, tags, salience, context }) => {
       try {
-        const id = await audrey.encode({ content, source, tags, salience });
+        const id = await audrey.encode({ content, source, tags, salience, context });
         return toolResult({ id, content, source });
       } catch (err) {
         return toolError(err);
@@ -179,13 +182,23 @@ async function main() {
       limit: z.number().min(1).max(50).optional().describe('Max results (default 10)'),
       types: z.array(z.enum(VALID_TYPES)).optional().describe('Memory types to search'),
       min_confidence: z.number().min(0).max(1).optional().describe('Minimum confidence threshold'),
+      tags: z.array(z.string()).optional().describe('Only return episodic memories with these tags'),
+      sources: z.array(z.enum(VALID_SOURCES)).optional().describe('Only return episodic memories from these sources'),
+      after: z.string().optional().describe('Only return memories created after this ISO date'),
+      before: z.string().optional().describe('Only return memories created before this ISO date'),
+      context: z.record(z.string()).optional().describe('Retrieval context — memories encoded in matching context get boosted'),
     },
-    async ({ query, limit, types, min_confidence }) => {
+    async ({ query, limit, types, min_confidence, tags, sources, after, before, context }) => {
       try {
         const results = await audrey.recall(query, {
           limit: limit ?? 10,
           types,
           minConfidence: min_confidence,
+          tags,
+          sources,
+          after,
+          before,
+          context,
         });
         return toolResult(results);
       } catch (err) {
@@ -279,6 +292,53 @@ async function main() {
     },
   );
 
+  server.tool(
+    'memory_forget',
+    {
+      id: z.string().optional().describe('ID of the memory to forget'),
+      query: z.string().optional().describe('Semantic query to find and forget the closest matching memory'),
+      min_similarity: z.number().min(0).max(1).optional().describe('Minimum similarity for query-based forget (default 0.9)'),
+      purge: z.boolean().optional().describe('Hard-delete the memory permanently (default false, soft-delete)'),
+    },
+    async ({ id, query, min_similarity, purge }) => {
+      try {
+        if (!id && !query) {
+          return toolError(new Error('Provide either id or query'));
+        }
+        let result;
+        if (id) {
+          result = audrey.forget(id, { purge: purge ?? false });
+        } else {
+          result = await audrey.forgetByQuery(query, {
+            minSimilarity: min_similarity ?? 0.9,
+            purge: purge ?? false,
+          });
+          if (!result) {
+            return toolResult({ forgotten: false, reason: 'No memory found above similarity threshold' });
+          }
+        }
+        return toolResult({ forgotten: true, ...result });
+      } catch (err) {
+        return toolError(err);
+      }
+    },
+  );
+
+  server.tool(
+    'memory_decay',
+    {
+      dormant_threshold: z.number().min(0).max(1).optional().describe('Confidence below which memories go dormant (default 0.1)'),
+    },
+    async ({ dormant_threshold }) => {
+      try {
+        const result = audrey.decay({ dormantThreshold: dormant_threshold });
+        return toolResult(result);
+      } catch (err) {
+        return toolError(err);
+      }
+    },
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('[audrey-mcp] connected via stdio');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audrey",
-  "version": "0.5.1",
+  "version": "0.8.0",
   "description": "Biological memory architecture for AI agents — encode, consolidate, and recall memories with confidence decay, contradiction detection, and causal graphs",
   "type": "module",
   "main": "src/index.js",

package/src/audrey.js

@@ -8,12 +8,14 @@ import { validateMemory } from './validate.js';
 import { runConsolidation } from './consolidate.js';
 import { applyDecay } from './decay.js';
 import { rollbackConsolidation, getConsolidationHistory } from './rollback.js';
+import { forgetMemory, forgetByQuery as forgetByQueryFn, purgeMemories } from './forget.js';
 import { introspect as introspectFn } from './introspect.js';
 import { buildContextResolutionPrompt } from './prompts.js';
 import { exportMemories } from './export.js';
 import { importMemories } from './import.js';
 import { suggestConsolidationParams as suggestParamsFn } from './adaptive.js';
 import { reembedAll } from './migrate.js';
+import { applyInterference } from './interference.js';
 
 /**
  * @typedef {'direct-observation' | 'told-by-user' | 'tool-result' | 'inference' | 'model-generated'} SourceType
@@ -33,6 +35,10 @@ import { reembedAll } from './migrate.js';
  * @property {number} [limit]
  * @property {boolean} [includeProvenance]
  * @property {boolean} [includeDormant]
+ * @property {string[]} [tags]
+ * @property {string[]} [sources]
+ * @property {string} [after]
+ * @property {string} [before]
  *
  * @typedef {Object} RecallResult
  * @property {string} id
@@ -84,6 +90,8 @@ export class Audrey extends EventEmitter {
     confidence = {},
     consolidation = {},
     decay = {},
+    interference = {},
+    context = {},
   } = {}) {
     super();
 
@@ -108,12 +116,24 @@ export class Audrey extends EventEmitter {
       weights: confidence.weights,
       halfLives: confidence.halfLives,
       sourceReliability: confidence.sourceReliability,
+      interferenceWeight: interference.weight ?? 0.1,
+      contextWeight: context.weight ?? 0.3,
     };
     this.consolidationConfig = {
       minEpisodes: consolidation.minEpisodes || 3,
     };
     this.decayConfig = { dormantThreshold: decay.dormantThreshold || 0.1 };
     this._autoConsolidateTimer = null;
+    this.interferenceConfig = {
+      enabled: interference.enabled ?? true,
+      k: interference.k ?? 5,
+      threshold: interference.threshold ?? 0.6,
+      weight: interference.weight ?? 0.1,
+    };
+    this.contextConfig = {
+      enabled: context.enabled ?? true,
+      weight: context.weight ?? 0.3,
+    };
   }
 
   async _ensureMigrated() {
@@ -155,6 +175,15 @@ export class Audrey extends EventEmitter {
     await this._ensureMigrated();
     const id = await encodeEpisode(this.db, this.embeddingProvider, params);
     this.emit('encode', { id, ...params });
+    if (this.interferenceConfig.enabled) {
+      applyInterference(this.db, this.embeddingProvider, id, params, this.interferenceConfig)
+        .then(affected => {
+          if (affected.length > 0) {
+            this.emit('interference', { episodeId: id, affected });
+          }
+        })
+        .catch(err => this.emit('error', err));
+    }
     this._emitValidation(id, params);
     return id;
   }
@@ -188,7 +217,7 @@ export class Audrey extends EventEmitter {
     await this._ensureMigrated();
     return recallFn(this.db, this.embeddingProvider, query, {
       ...options,
-      confidenceConfig: options.confidenceConfig ?? this.confidenceConfig,
+      confidenceConfig: this._recallConfig(options),
     });
   }
 
@@ -201,10 +230,17 @@ export class Audrey extends EventEmitter {
     await this._ensureMigrated();
     yield* recallStreamFn(this.db, this.embeddingProvider, query, {
       ...options,
-      confidenceConfig: options.confidenceConfig ?? this.confidenceConfig,
+      confidenceConfig: this._recallConfig(options),
     });
   }
 
+  _recallConfig(options) {
+    const base = options.confidenceConfig ?? this.confidenceConfig;
+    return this.contextConfig.enabled && options.context
+      ? { ...base, retrievalContext: options.context }
+      : base;
+  }
+
   /**
    * @param {{ minClusterSize?: number, similarityThreshold?: number, extractPrinciple?: Function, llmProvider?: import('./llm.js').LLMProvider }} [options]
    * @returns {Promise<ConsolidationResult>}
@@ -343,6 +379,25 @@ export class Audrey extends EventEmitter {
     return suggestParamsFn(this.db);
   }
 
+  forget(id, options = {}) {
+    const result = forgetMemory(this.db, id, options);
+    this.emit('forget', result);
+    return result;
+  }
+
+  async forgetByQuery(query, options = {}) {
+    await this._ensureMigrated();
+    const result = await forgetByQueryFn(this.db, this.embeddingProvider, query, options);
+    if (result) this.emit('forget', result);
+    return result;
+  }
+
+  purge() {
+    const result = purgeMemories(this.db);
+    this.emit('purge', result);
+    return result;
+  }
+
   /** @returns {void} */
   close() {
     this.stopAutoConsolidate();

package/src/confidence.js

@@ -67,8 +67,16 @@ export function recencyDecay(ageDays, halfLifeDays) {
  */
 export function retrievalReinforcement(retrievalCount, daysSinceRetrieval) {
   if (retrievalCount === 0) return 0;
-  const lambdaRet = Math.LN2 / 14; // 14-day half-life for retrieval decay
-  return Math.min(1.0, 0.3 * Math.log(1 + retrievalCount) * Math.exp(-lambdaRet * daysSinceRetrieval));
+  const lambdaRet = Math.LN2 / 14;
+  const baseReinforcement = 0.3 * Math.log(1 + retrievalCount);
+  const recencyWeight = Math.exp(-lambdaRet * daysSinceRetrieval);
+  const spacedBonus = Math.min(0.15, 0.02 * Math.log(1 + daysSinceRetrieval));
+  return Math.min(1.0, baseReinforcement * recencyWeight + spacedBonus);
+}
+
+export function salienceModifier(salience) {
+  const s = salience ?? 0.5;
+  return 0.5 + s;
 }
 
 /**

package/src/consolidate.js

@@ -152,6 +152,7 @@ export async function runConsolidation(db, embeddingProvider, options = {}) {
         embeddingBuffer,
         semanticId: generateId(),
         semanticNow: new Date().toISOString(),
+        maxSalience: Math.max(...cluster.map(ep => ep.salience ?? 0.5)),
       });
     }
 
@@ -168,8 +169,8 @@ export async function runConsolidation(db, embeddingProvider, options = {}) {
             id, content, embedding, state, evidence_episode_ids,
             evidence_count, supporting_count, source_type_diversity,
             consolidation_checkpoint, embedding_model, embedding_version,
-            consolidation_model, created_at
-          ) VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            consolidation_model, created_at, salience
+          ) VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         `).run(
           entry.semanticId,
           entry.principle.content,
@@ -183,6 +184,7 @@ export async function runConsolidation(db, embeddingProvider, options = {}) {
           embeddingProvider.modelVersion,
           llmProvider?.modelName || null,
           entry.semanticNow,
+          entry.maxSalience,
         );
 
         db.prepare('INSERT INTO vec_semantics(id, embedding, state) VALUES (?, ?, ?)').run(

package/src/context.js

@@ -0,0 +1,15 @@
+export function contextMatchRatio(encodingContext, retrievalContext) {
+  if (!encodingContext || !retrievalContext) return 0;
+  const retrievalKeys = Object.keys(retrievalContext);
+  if (retrievalKeys.length === 0) return 0;
+  const sharedKeys = retrievalKeys.filter(k => k in encodingContext);
+  if (sharedKeys.length === 0) return 0;
+  const matches = sharedKeys.filter(k => encodingContext[k] === retrievalContext[k]).length;
+  return matches / retrievalKeys.length;
+}
+
+export function contextModifier(encodingContext, retrievalContext, weight = 0.3) {
+  if (!encodingContext || !retrievalContext) return 1.0;
+  const ratio = contextMatchRatio(encodingContext, retrievalContext);
+  return 1.0 + (weight * ratio);
+}

package/src/db.js

@@ -11,6 +11,7 @@ const SCHEMA = `
     source TEXT NOT NULL CHECK(source IN ('direct-observation','told-by-user','tool-result','inference','model-generated')),
     source_reliability REAL NOT NULL,
     salience REAL DEFAULT 0.5,
+    context TEXT DEFAULT '{}',
     tags TEXT,
     causal_trigger TEXT,
     causal_consequence TEXT,
@@ -42,7 +43,9 @@ const SCHEMA = `
     created_at TEXT NOT NULL,
     last_reinforced_at TEXT,
     retrieval_count INTEGER DEFAULT 0,
-    challenge_count INTEGER DEFAULT 0
+    challenge_count INTEGER DEFAULT 0,
+    interference_count INTEGER DEFAULT 0,
+    salience REAL DEFAULT 0.5
   );
 
   CREATE TABLE IF NOT EXISTS procedures (
@@ -58,7 +61,9 @@ const SCHEMA = `
     embedding_version TEXT,
     created_at TEXT NOT NULL,
     last_reinforced_at TEXT,
-    retrieval_count INTEGER DEFAULT 0
+    retrieval_count INTEGER DEFAULT 0,
+    interference_count INTEGER DEFAULT 0,
+    salience REAL DEFAULT 0.5
   );
 
   CREATE TABLE IF NOT EXISTS causal_links (

package/src/decay.js

@@ -1,4 +1,5 @@
-import { computeConfidence, DEFAULT_HALF_LIVES } from './confidence.js';
+import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier } from './confidence.js';
+import { interferenceModifier } from './interference.js';
 import { daysBetween } from './utils.js';
 
 /**
@@ -13,7 +14,7 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
 
   const semantics = db.prepare(`
     SELECT id, supporting_count, contradicting_count, created_at,
-           last_reinforced_at, retrieval_count
+           last_reinforced_at, retrieval_count, interference_count, salience
     FROM semantics WHERE state = 'active'
   `).all();
 
@@ -26,7 +27,7 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
       ? daysBetween(sem.last_reinforced_at, now)
       : ageDays;
 
-    const confidence = computeConfidence({
+    let confidence = computeConfidence({
       sourceType: 'tool-result',
       supportingCount: sem.supporting_count || 0,
       contradictingCount: sem.contradicting_count || 0,
@@ -35,6 +36,9 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
       retrievalCount: sem.retrieval_count || 0,
       daysSinceRetrieval,
     });
+    confidence *= interferenceModifier(sem.interference_count || 0);
+    confidence *= salienceModifier(sem.salience ?? 0.5);
+    confidence = Math.max(0, Math.min(1, confidence));
 
     if (confidence < dormantThreshold) {
       markDormantSem.run('dormant', sem.id);
@@ -44,7 +48,7 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
 
   const procedures = db.prepare(`
     SELECT id, success_count, failure_count, created_at,
-           last_reinforced_at, retrieval_count
+           last_reinforced_at, retrieval_count, interference_count, salience
     FROM procedures WHERE state = 'active'
   `).all();
 
@@ -57,7 +61,7 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
       ? daysBetween(proc.last_reinforced_at, now)
       : ageDays;
 
-    const confidence = computeConfidence({
+    let confidence = computeConfidence({
       sourceType: 'tool-result',
       supportingCount: proc.success_count || 0,
       contradictingCount: proc.failure_count || 0,
@@ -66,6 +70,9 @@ export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
       retrievalCount: proc.retrieval_count || 0,
       daysSinceRetrieval,
     });
+    confidence *= interferenceModifier(proc.interference_count || 0);
+    confidence *= salienceModifier(proc.salience ?? 0.5);
+    confidence = Math.max(0, Math.min(1, confidence));
 
     if (confidence < dormantThreshold) {
       markDormantProc.run('dormant', proc.id);

package/src/encode.js

@@ -14,6 +14,7 @@ export async function encodeEpisode(db, embeddingProvider, {
   causal,
   tags,
   supersedes,
+  context = {},
 }) {
   if (!content || typeof content !== 'string') throw new Error('content must be a non-empty string');
   if (salience < 0 || salience > 1) throw new Error('salience must be between 0 and 1');
@@ -28,12 +29,13 @@ export async function encodeEpisode(db, embeddingProvider, {
   const insertAndLink = db.transaction(() => {
     db.prepare(`
       INSERT INTO episodes (
-        id, content, embedding, source, source_reliability, salience,
+        id, content, embedding, source, source_reliability, salience, context,
         tags, causal_trigger, causal_consequence, created_at,
         embedding_model, embedding_version, supersedes
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id, content, embeddingBuffer, source, reliability, salience,
+      JSON.stringify(context),
       tags ? JSON.stringify(tags) : null,
       causal?.trigger || null, causal?.consequence || null,
       now, embeddingProvider.modelName, embeddingProvider.modelVersion,

package/src/forget.js

@@ -0,0 +1,111 @@
+export function forgetMemory(db, id, { purge = false } = {}) {
+  const episode = db.prepare('SELECT id FROM episodes WHERE id = ?').get(id);
+  if (episode) {
+    if (purge) {
+      db.prepare('DELETE FROM vec_episodes WHERE id = ?').run(id);
+      db.prepare('DELETE FROM episodes WHERE id = ?').run(id);
+    } else {
+      db.prepare("UPDATE episodes SET superseded_by = 'forgotten' WHERE id = ?").run(id);
+      db.prepare('DELETE FROM vec_episodes WHERE id = ?').run(id);
+    }
+    return { id, type: 'episodic', purged: purge };
+  }
+
+  const semantic = db.prepare('SELECT id FROM semantics WHERE id = ?').get(id);
+  if (semantic) {
+    if (purge) {
+      db.prepare('DELETE FROM vec_semantics WHERE id = ?').run(id);
+      db.prepare('DELETE FROM semantics WHERE id = ?').run(id);
+    } else {
+      db.prepare("UPDATE semantics SET state = 'superseded' WHERE id = ?").run(id);
+      db.prepare('DELETE FROM vec_semantics WHERE id = ?').run(id);
+    }
+    return { id, type: 'semantic', purged: purge };
+  }
+
+  const procedure = db.prepare('SELECT id FROM procedures WHERE id = ?').get(id);
+  if (procedure) {
+    if (purge) {
+      db.prepare('DELETE FROM vec_procedures WHERE id = ?').run(id);
+      db.prepare('DELETE FROM procedures WHERE id = ?').run(id);
+    } else {
+      db.prepare("UPDATE procedures SET state = 'superseded' WHERE id = ?").run(id);
+      db.prepare('DELETE FROM vec_procedures WHERE id = ?').run(id);
+    }
+    return { id, type: 'procedural', purged: purge };
+  }
+
+  throw new Error(`Memory not found: ${id}`);
+}
+
+export function purgeMemories(db) {
+  const deadEpisodes = db.prepare(
+    'SELECT id FROM episodes WHERE superseded_by IS NOT NULL'
+  ).all();
+  const deadSemantics = db.prepare(
+    "SELECT id FROM semantics WHERE state IN ('superseded', 'dormant', 'rolled_back')"
+  ).all();
+  const deadProcedures = db.prepare(
+    "SELECT id FROM procedures WHERE state IN ('superseded', 'dormant', 'rolled_back')"
+  ).all();
+
+  const purgeAll = db.transaction(() => {
+    for (const row of deadEpisodes) {
+      db.prepare('DELETE FROM vec_episodes WHERE id = ?').run(row.id);
+      db.prepare('DELETE FROM episodes WHERE id = ?').run(row.id);
+    }
+    for (const row of deadSemantics) {
+      db.prepare('DELETE FROM vec_semantics WHERE id = ?').run(row.id);
+      db.prepare('DELETE FROM semantics WHERE id = ?').run(row.id);
+    }
+    for (const row of deadProcedures) {
+      db.prepare('DELETE FROM vec_procedures WHERE id = ?').run(row.id);
+      db.prepare('DELETE FROM procedures WHERE id = ?').run(row.id);
+    }
+  });
+
+  purgeAll();
+
+  return {
+    episodes: deadEpisodes.length,
+    semantics: deadSemantics.length,
+    procedures: deadProcedures.length,
+  };
+}
+
+export async function forgetByQuery(db, embeddingProvider, query, { minSimilarity = 0.9, purge = false } = {}) {
+  const queryVector = await embeddingProvider.embed(query);
+  const queryBuffer = embeddingProvider.vectorToBuffer(queryVector);
+
+  const candidates = [];
+
+  const epMatch = db.prepare(`
+    SELECT e.id, (1.0 - v.distance) AS similarity, 'episodic' AS type
+    FROM vec_episodes v JOIN episodes e ON e.id = v.id
+    WHERE v.embedding MATCH ? AND k = 1 AND e.superseded_by IS NULL
+  `).get(queryBuffer);
+  if (epMatch) candidates.push(epMatch);
+
+  const semMatch = db.prepare(`
+    SELECT s.id, (1.0 - v.distance) AS similarity, 'semantic' AS type
+    FROM vec_semantics v JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ? AND k = 1 AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).get(queryBuffer);
+  if (semMatch) candidates.push(semMatch);
+
+  const procMatch = db.prepare(`
+    SELECT p.id, (1.0 - v.distance) AS similarity, 'procedural' AS type
+    FROM vec_procedures v JOIN procedures p ON p.id = v.id
+    WHERE v.embedding MATCH ? AND k = 1 AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).get(queryBuffer);
+  if (procMatch) candidates.push(procMatch);
+
+  if (candidates.length === 0) return null;
+
+  candidates.sort((a, b) => b.similarity - a.similarity);
+  const best = candidates[0];
+
+  if (best.similarity < minSimilarity) return null;
+
+  return forgetMemory(db, best.id, { purge });
+}

package/src/index.js

@@ -1,5 +1,5 @@
 export { Audrey } from './audrey.js';
-export { computeConfidence, sourceReliability, DEFAULT_SOURCE_RELIABILITY, DEFAULT_WEIGHTS, DEFAULT_HALF_LIVES } from './confidence.js';
+export { computeConfidence, sourceReliability, salienceModifier, DEFAULT_SOURCE_RELIABILITY, DEFAULT_WEIGHTS, DEFAULT_HALF_LIVES } from './confidence.js';
 export { createEmbeddingProvider, MockEmbeddingProvider, OpenAIEmbeddingProvider } from './embedding.js';
 export { createLLMProvider, MockLLMProvider, AnthropicLLMProvider, OpenAILLMProvider } from './llm.js';
 export { recall, recallStream } from './recall.js';
@@ -14,3 +14,6 @@ export { exportMemories } from './export.js';
 export { importMemories } from './import.js';
 export { suggestConsolidationParams } from './adaptive.js';
 export { reembedAll } from './migrate.js';
+export { forgetMemory, forgetByQuery, purgeMemories } from './forget.js';
+export { applyInterference, interferenceModifier } from './interference.js';
+export { contextMatchRatio, contextModifier } from './context.js';

package/src/interference.js

@@ -0,0 +1,51 @@
+export function interferenceModifier(interferenceCount, weight = 0.1) {
+  return 1 / (1 + weight * interferenceCount);
+}
+
+export async function applyInterference(db, embeddingProvider, episodeId, { content }, config = {}) {
+  const { enabled = true, k = 5, threshold = 0.6, weight = 0.1 } = config;
+
+  if (!enabled) return [];
+
+  const vector = await embeddingProvider.embed(content);
+  const buffer = embeddingProvider.vectorToBuffer(vector);
+
+  const semanticHits = db.prepare(`
+    SELECT s.id, s.interference_count, (1.0 - v.distance) AS similarity
+    FROM vec_semantics v
+    JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).all(buffer, k);
+
+  const proceduralHits = db.prepare(`
+    SELECT p.id, p.interference_count, (1.0 - v.distance) AS similarity
+    FROM vec_procedures v
+    JOIN procedures p ON p.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).all(buffer, k);
+
+  const affected = [];
+
+  const updateSemantic = db.prepare('UPDATE semantics SET interference_count = ? WHERE id = ?');
+  const updateProcedural = db.prepare('UPDATE procedures SET interference_count = ? WHERE id = ?');
+
+  for (const hit of semanticHits) {
+    if (hit.similarity < threshold) continue;
+    const newCount = hit.interference_count + 1;
+    updateSemantic.run(newCount, hit.id);
+    affected.push({ id: hit.id, type: 'semantic', newCount, similarity: hit.similarity });
+  }
+
+  for (const hit of proceduralHits) {
+    if (hit.similarity < threshold) continue;
+    const newCount = hit.interference_count + 1;
+    updateProcedural.run(newCount, hit.id);
+    affected.push({ id: hit.id, type: 'procedural', newCount, similarity: hit.similarity });
+  }
+
+  return affected;
+}

package/src/recall.js

@@ -1,10 +1,12 @@
-import { computeConfidence, DEFAULT_HALF_LIVES } from './confidence.js';
+import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier } from './confidence.js';
+import { interferenceModifier } from './interference.js';
+import { contextMatchRatio, contextModifier } from './context.js';
 import { daysBetween, safeJsonParse } from './utils.js';
 
 function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
   const ageDays = daysBetween(ep.created_at, now);
   const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
-  return computeConfidence({
+  let confidence = computeConfidence({
     sourceType: ep.source,
     supportingCount: 1,
     contradictingCount: 0,
@@ -15,6 +17,8 @@ function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
     weights: confidenceConfig.weights,
     customSourceReliability: confidenceConfig.sourceReliability,
   });
+  confidence *= salienceModifier(ep.salience);
+  return Math.max(0, Math.min(1, confidence));
 }
 
 function computeSemanticConfidence(sem, now, confidenceConfig = {}) {
@@ -23,7 +27,7 @@ function computeSemanticConfidence(sem, now, confidenceConfig = {}) {
     ? daysBetween(sem.last_reinforced_at, now)
     : ageDays;
   const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
-  return computeConfidence({
+  let confidence = computeConfidence({
     sourceType: 'tool-result',
     supportingCount: sem.supporting_count || 0,
     contradictingCount: sem.contradicting_count || 0,
@@ -34,6 +38,9 @@ function computeSemanticConfidence(sem, now, confidenceConfig = {}) {
     weights: confidenceConfig.weights,
     customSourceReliability: confidenceConfig.sourceReliability,
   });
+  confidence *= interferenceModifier(sem.interference_count || 0, confidenceConfig.interferenceWeight);
+  confidence *= salienceModifier(sem.salience);
+  return Math.max(0, Math.min(1, confidence));
 }
 
 function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
@@ -42,7 +49,7 @@ function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
     ? daysBetween(proc.last_reinforced_at, now)
     : ageDays;
   const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
-  return computeConfidence({
+  let confidence = computeConfidence({
     sourceType: 'tool-result',
     supportingCount: proc.success_count || 0,
     contradictingCount: proc.failure_count || 0,
@@ -53,9 +60,12 @@ function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
     weights: confidenceConfig.weights,
     customSourceReliability: confidenceConfig.sourceReliability,
   });
+  confidence *= interferenceModifier(proc.interference_count || 0, confidenceConfig.interferenceWeight);
+  confidence *= salienceModifier(proc.salience);
+  return Math.max(0, Math.min(1, confidence));
 }
 
-function buildEpisodicEntry(ep, confidence, score, includeProvenance) {
+function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMatch) {
   const entry = {
     id: ep.id,
     content: ep.content,
@@ -65,6 +75,9 @@ function buildEpisodicEntry(ep, confidence, score, includeProvenance) {
     source: ep.source,
     createdAt: ep.created_at,
   };
+  if (contextMatch !== undefined) {
+    entry.contextMatch = contextMatch;
+  }
   if (includeProvenance) {
     entry.provenance = {
       source: ep.source,
@@ -121,7 +134,19 @@ function buildProceduralEntry(proc, confidence, score, includeProvenance) {
   return entry;
 }
 
-function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig) {
+function stateClause(includeDormant) {
+  return includeDormant
+    ? "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')"
+    : "AND (v.state = 'active' OR v.state = 'context_dependent')";
+}
+
+function matchesDateFilters(createdAt, filters) {
+  if (filters.after && createdAt <= filters.after) return false;
+  if (filters.before && createdAt >= filters.before) return false;
+  return true;
+}
+
+function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters = {}) {
   const rows = db.prepare(`
     SELECT e.*, (1.0 - v.distance) AS similarity
     FROM vec_episodes v
@@ -133,34 +158,43 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
 
   const results = [];
   for (const row of rows) {
-    const confidence = computeEpisodicConfidence(row, now, confidenceConfig);
+    if (!matchesDateFilters(row.created_at, filters)) continue;
+    if (filters.tags?.length) {
+      const rowTags = safeJsonParse(row.tags, []);
+      if (!filters.tags.some(t => rowTags.includes(t))) continue;
+    }
+    if (filters.sources?.length && !filters.sources.includes(row.source)) continue;
+    let confidence = computeEpisodicConfidence(row, now, confidenceConfig);
+
+    let ctxMatch;
+    if (confidenceConfig?.retrievalContext) {
+      const encodingCtx = safeJsonParse(row.context, {});
+      ctxMatch = contextMatchRatio(encodingCtx, confidenceConfig.retrievalContext);
+      confidence *= contextModifier(encodingCtx, confidenceConfig.retrievalContext, confidenceConfig.contextWeight);
+      confidence = Math.max(0, Math.min(1, confidence));
+    }
+
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
-    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance));
+    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance, ctxMatch));
   }
   return results;
 }
 
-function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig) {
-  let stateFilter;
-  if (includeDormant) {
-    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
-  } else {
-    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent')";
-  }
-
+function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}) {
   const rows = db.prepare(`
     SELECT s.*, (1.0 - v.distance) AS similarity
     FROM vec_semantics v
     JOIN semantics s ON s.id = v.id
     WHERE v.embedding MATCH ?
       AND k = ?
-      ${stateFilter}
+      ${stateClause(includeDormant)}
   `).all(queryBuffer, candidateK);
 
   const results = [];
   const matchedIds = [];
   for (const row of rows) {
+    if (!matchesDateFilters(row.created_at, filters)) continue;
     const confidence = computeSemanticConfidence(row, now, confidenceConfig);
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
@@ -170,26 +204,20 @@ function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includePro
   return { results, matchedIds };
 }
 
-function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig) {
-  let stateFilter;
-  if (includeDormant) {
-    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
-  } else {
-    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent')";
-  }
-
+function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}) {
   const rows = db.prepare(`
     SELECT p.*, (1.0 - v.distance) AS similarity
     FROM vec_procedures v
     JOIN procedures p ON p.id = v.id
     WHERE v.embedding MATCH ?
       AND k = ?
-      ${stateFilter}
+      ${stateClause(includeDormant)}
   `).all(queryBuffer, candidateK);
 
   const results = [];
   const matchedIds = [];
   for (const row of rows) {
+    if (!matchesDateFilters(row.created_at, filters)) continue;
     const confidence = computeProceduralConfidence(row, now, confidenceConfig);
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
@@ -203,7 +231,7 @@ function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeP
  * @param {import('better-sqlite3').Database} db
  * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
  * @param {string} query
- * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean }} [options]
+ * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean, tags?: string[], sources?: string[], after?: string, before?: string }} [options]
  * @returns {AsyncGenerator<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>}
  */
 export async function* recallStream(db, embeddingProvider, query, options = {}) {
@@ -214,24 +242,30 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     includeProvenance = false,
     includeDormant = false,
     confidenceConfig,
+    tags,
+    sources,
+    after,
+    before,
   } = options;
 
   const queryVector = await embeddingProvider.embed(query);
   const queryBuffer = embeddingProvider.vectorToBuffer(queryVector);
   const searchTypes = types || ['episodic', 'semantic', 'procedural'];
   const now = new Date();
-  const candidateK = limit * 3;
+  const hasFilters = tags?.length || sources?.length || after || before;
+  const candidateK = hasFilters ? limit * 5 : limit * 3;
+  const filters = { tags, sources, after, before };
 
   const allResults = [];
 
   if (searchTypes.includes('episodic')) {
-    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig);
+    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters);
     allResults.push(...episodic);
   }
 
   if (searchTypes.includes('semantic')) {
     const { results: semResults, matchedIds: semIds } =
-      knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig);
+      knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters);
     allResults.push(...semResults);
 
     if (semIds.length > 0) {
@@ -247,7 +281,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
 
   if (searchTypes.includes('procedural')) {
     const { results: procResults, matchedIds: procIds } =
-      knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig);
+      knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters);
     allResults.push(...procResults);
 
     if (procIds.length > 0) {
@@ -272,7 +306,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
  * @param {import('better-sqlite3').Database} db
  * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
  * @param {string} query
- * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean }} [options]
+ * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean, tags?: string[], sources?: string[], after?: string, before?: string }} [options]
  * @returns {Promise<Array<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>>}
  */
 export async function recall(db, embeddingProvider, query, options = {}) {