major(llm): Support Embedding Providers

feat(memory): Implemented tier two memory retrieval using cognition model
2026-07-22 03:52:48 +05:30 · 2026-07-11 14:31:18 +05:30 · 2026-07-11 13:57:27 +05:30
16 changed files with 1057 additions and 151 deletions
--- a/apps/gui/next-env.d.ts
+++ b/apps/gui/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";

 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
--- a/apps/gui/src/app/config/page.tsx
+++ b/apps/gui/src/app/config/page.tsx
@@ -11,8 +11,9 @@ import {
  setProviderMapping,
  updateProviderInstance,
  getAvailableProviders,
+  regenerateEmbeddings,
 } from "@/app/play/actions";
-import type { LLMProviderInstance, LLMProviderMeta } from "@omnia/llm";
+import type { ModelProviderInstance, ModelProviderMeta } from "@omnia/llm";

 interface ConfigStatus {
  apiKeySet: boolean;
@@ -23,9 +24,9 @@ interface ConfigStatus {

 export default function ConfigPage() {
  const [config, setConfig] = useState<ConfigStatus | null>(null);
-  const [instances, setInstances] = useState<LLMProviderInstance[]>([]);
+  const [instances, setInstances] = useState<ModelProviderInstance[]>([]);
  const [mappings, setMappings] = useState<Record<string, string>>({});
-  const [availableProviders, setAvailableProviders] = useState<LLMProviderMeta[]>([]);
+  const [availableProviders, setAvailableProviders] = useState<ModelProviderMeta[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");

@@ -35,6 +36,7 @@ export default function ConfigPage() {
  const [editKey, setEditKey] = useState("");
  const [editModel, setEditModel] = useState("gemini-2.5-flash");
  const [editIsActive, setEditIsActive] = useState(false);
+  const [editType, setEditType] = useState<"generative" | "embedding">("generative");

  useEffect(() => {
    if (selectedInstanceId === "new") {
@@ -42,6 +44,7 @@ export default function ConfigPage() {
      const defaultProvider = "google-genai";
      setEditProvider(defaultProvider);
      setEditKey("");
+      setEditType("generative");
      const pMeta = availableProviders.find((p) => p.id === defaultProvider);
      setEditModel(pMeta?.defaultModel || "gemini-2.5-flash");
      setEditIsActive(false);
@@ -51,8 +54,9 @@ export default function ConfigPage() {
        setEditName(inst.name);
        setEditProvider(inst.providerName);
        setEditKey("");
+        setEditType(inst.type || "generative");
        const pMeta = availableProviders.find((p) => p.id === inst.providerName);
-        setEditModel(inst.modelName || pMeta?.defaultModel || "gemini-2.5-flash");
+        setEditModel(inst.modelName || (inst.type === "embedding" ? pMeta?.defaultEmbeddingModel : pMeta?.defaultModel) || "gemini-2.5-flash");
        setEditIsActive(inst.isActive);
      }
    }
@@ -62,7 +66,15 @@ export default function ConfigPage() {
    setEditProvider(providerId);
    const pMeta = availableProviders.find((p) => p.id === providerId);
    if (pMeta) {
-      setEditModel(pMeta.defaultModel);
+      setEditModel(editType === "embedding" ? pMeta.defaultEmbeddingModel : pMeta.defaultModel);
+    }
+  };
+
+  const handleTypeChange = (type: "generative" | "embedding") => {
+    setEditType(type);
+    const pMeta = availableProviders.find((p) => p.id === editProvider);
+    if (pMeta) {
+      setEditModel(type === "embedding" ? pMeta.defaultEmbeddingModel : pMeta.defaultModel);
    }
  };

@@ -116,19 +128,42 @@ export default function ConfigPage() {
      setLoading(true);
      setError("");

+      let shouldRegenerate = false;
+      let targetInstanceId = selectedInstanceId;
+
      if (selectedInstanceId === "new") {
        if (!editKey.trim()) {
          setError("API Key is required for new instances.");
          setLoading(false);
          return;
        }
-        const created = await createProviderInstance(editName, editProvider, editKey, editModel || undefined);
+        const created = await createProviderInstance(editName, editProvider, editKey, editModel || undefined, editType);
        if (editIsActive) {
          await setActiveProviderInstance(created.id);
        }
+        targetInstanceId = created.id;
        setSelectedInstanceId(created.id);
      } else {
-        await updateProviderInstance(selectedInstanceId, editName, editProvider, editKey || undefined, editModel || undefined);
+        const inst = instances.find((i) => i.id === selectedInstanceId);
+        if (inst && inst.type === "embedding") {
+          const isMapped = mappings["embeddings"] === selectedInstanceId;
+          const isActive = inst.isActive && !mappings["embeddings"];
+          if (isMapped || isActive) {
+            const hasChanged = inst.providerName !== editProvider || inst.modelName !== editModel;
+            if (hasChanged) {
+              const confirmChange = window.confirm(
+                "You have changed the configuration of the active embedding provider. This will delete all existing embeddings and regenerate them from scratch. Are you sure you want to do this?"
+              );
+              if (!confirmChange) {
+                setLoading(false);
+                return;
+              }
+              shouldRegenerate = true;
+            }
+          }
+        }
+
+        await updateProviderInstance(selectedInstanceId, editName, editProvider, editKey || undefined, editModel || undefined, editType);
        if (editIsActive) {
          await setActiveProviderInstance(selectedInstanceId);
        }
@@ -136,6 +171,10 @@ export default function ConfigPage() {

      await loadInstances();
      await loadMappings();
+
+      if (shouldRegenerate && targetInstanceId !== "new") {
+        await regenerateEmbeddings(targetInstanceId);
+      }
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    } finally {
@@ -162,9 +201,19 @@ export default function ConfigPage() {
  };

  const handleUpdateMapping = async (task: string, providerInstanceId: string) => {
+    if (task === "embeddings" && mappings[task] !== providerInstanceId) {
+      const confirmChange = window.confirm(
+        "Changing the embeddings provider will delete all existing embeddings and regenerate them from scratch. Are you sure you want to do this?"
+      );
+      if (!confirmChange) return;
+    }
+
    try {
      setLoading(true);
      await setProviderMapping(task, providerInstanceId);
+      if (task === "embeddings") {
+        await regenerateEmbeddings(providerInstanceId);
+      }
      await loadMappings();
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
@@ -219,7 +268,7 @@ export default function ConfigPage() {
                      >
                        <div className="text-sm font-medium text-[#111]">{inst.name}</div>
                        <div className="mt-1 flex items-center justify-between text-xs text-gray-500">
-                          <span>{inst.providerName}</span>
+                          <span>{inst.providerName} ({inst.type || "generative"})</span>
                          {inst.isActive && (
                            <span className="rounded-full bg-green-100 px-1.5 py-[1px] text-[0.65rem] font-semibold text-green-700">
                              Active
@@ -257,6 +306,21 @@ export default function ConfigPage() {
                      />
                    </div>

+                    <div className="flex flex-col gap-1.5">
+                      <label htmlFor="formType" className="text-xs font-medium text-gray-700">
+                        Instance Type
+                      </label>
+                      <select
+                        id="formType"
+                        value={editType}
+                        onChange={(e) => handleTypeChange(e.target.value as "generative" | "embedding")}
+                        className="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm outline-none transition-[border-color,box-shadow] focus:border-blue-500 focus:ring-3 focus:ring-blue-500/15"
+                      >
+                        <option value="generative">Generative (Chat / Text Completion)</option>
+                        <option value="embedding">Embedding (Vector generation)</option>
+                      </select>
+                    </div>
+
                    <div className="flex flex-col gap-1.5">
                      <label htmlFor="formProvider" className="text-xs font-medium text-gray-700">
                        Provider Type
@@ -364,10 +428,11 @@ export default function ConfigPage() {
            </p>
            <div className="mt-4 grid grid-cols-1 gap-4 md:grid-cols-2">
              {[
-                { key: "actor-prose", label: "Actor Prose Generation", desc: "Generates roleplay/narrative prose for Non-Player Characters." },
-                { key: "llm-validator", label: "LLM Validator", desc: "Arbitrates and validates proposed actions against the world state rules." },
-                { key: "intent-decoder", label: "Intent Decoder", desc: "Splits raw prose actions into structured intents (Player and NPC)." },
-                { key: "timedelta", label: "TimeDelta Generator", desc: "Calculates the duration of character actions to advance the game clock." },
+                { key: "actor-prose", label: "Actor Prose Generation", desc: "Generates roleplay/narrative prose for Non-Player Characters.", type: "generative" },
+                { key: "llm-validator", label: "LLM Validator", desc: "Arbitrates and validates proposed actions against the world state rules.", type: "generative" },
+                { key: "intent-decoder", label: "Intent Decoder", desc: "Splits raw prose actions into structured intents (Player and NPC).", type: "generative" },
+                { key: "timedelta", label: "TimeDelta Generator", desc: "Calculates the duration of character actions to advance the game clock.", type: "generative" },
+                { key: "embeddings", label: "Text Embeddings Generator", desc: "Generates vector embeddings for long-term memory retrieval.", type: "embedding" },
              ].map((task) => (
                <div
                  key={task.key}
@@ -383,11 +448,13 @@ export default function ConfigPage() {
                    className="w-full rounded border border-gray-300 bg-white px-2 py-1.5 text-xs"
                  >
                    <option value="">-- Use Active Key (Default) --</option>
-                    {instances.map((inst) => (
-                      <option key={inst.id} value={inst.id}>
-                        {inst.name} ({inst.providerName}){inst.isActive ? " [Active]" : ""}
-                      </option>
-                    ))}
+                    {instances
+                      .filter((inst) => (inst.type || "generative") === task.type)
+                      .map((inst) => (
+                        <option key={inst.id} value={inst.id}>
+                          {inst.name} ({inst.providerName}){inst.isActive ? " [Active]" : ""}
+                        </option>
+                      ))}
                  </select>
                </div>
              ))}
--- a/apps/gui/src/app/play/actions.ts
+++ b/apps/gui/src/app/play/actions.ts
@@ -4,7 +4,7 @@ import path from "path";
 import fs from "fs";
 import { simulationManager } from "@/lib/simulation";
 import type { SimSnapshot } from "@/lib/simulation";
-import { ProviderManager, LLMProviderInstance, AVAILABLE_PROVIDERS, LLMProviderMeta } from "@omnia/llm";
+import { ProviderManager, ModelProviderInstance, AVAILABLE_PROVIDERS, ModelProviderMeta } from "@omnia/llm";

 function resolveScenarioPath(relative: string): string {
  const cwd = process.cwd();
@@ -233,7 +233,7 @@ export async function deleteSimulation(simId: string): Promise<
  }
 }

-export async function listProviderInstances(): Promise<LLMProviderInstance[]> {
+export async function listProviderInstances(): Promise<ModelProviderInstance[]> {
  return ProviderManager.list();
 }

@@ -242,8 +242,9 @@ export async function createProviderInstance(
  providerName: string,
  apiKey: string,
  modelName?: string,
-): Promise<LLMProviderInstance> {
-  return ProviderManager.create(name, providerName, apiKey, modelName);
+  type: "generative" | "embedding" = "generative",
+): Promise<ModelProviderInstance> {
+  return ProviderManager.create(name, providerName, apiKey, modelName, type);
 }

 export async function deleteProviderInstance(id: string): Promise<void> {
@@ -260,8 +261,9 @@ export async function updateProviderInstance(
  providerName: string,
  apiKey?: string,
  modelName?: string,
+  type: "generative" | "embedding" = "generative",
 ): Promise<void> {
-  ProviderManager.update(id, name, providerName, apiKey, modelName);
+  ProviderManager.update(id, name, providerName, apiKey, modelName, type);
 }

 export async function getProviderMappings(): Promise<Record<string, string>> {
@@ -275,6 +277,10 @@ export async function setProviderMapping(
  ProviderManager.setMapping(task, providerInstanceId);
 }

-export async function getAvailableProviders(): Promise<LLMProviderMeta[]> {
+export async function getAvailableProviders(): Promise<ModelProviderMeta[]> {
  return AVAILABLE_PROVIDERS;
 }
+
+export async function regenerateEmbeddings(newProviderInstanceId?: string): Promise<void> {
+  await simulationManager.regenerateAllEmbeddings(newProviderInstanceId);
+}
--- a/apps/gui/src/lib/simulation.ts
+++ b/apps/gui/src/lib/simulation.ts
@@ -17,7 +17,7 @@ for (const c of envCandidates) {
  }
 }

-import { BufferRepository } from "@omnia/memory";
+import { BufferRepository, LedgerRepository } from "@omnia/memory";
 import { Architect, AliasDeltaGenerator } from "@omnia/architect";
 import {
  ActorAgent,
@@ -25,7 +25,7 @@ import {
  IActorProseGenerator,
  buildBufferEntryForIntent,
 } from "@omnia/actor";
-import { GeminiProvider, ILLMProvider, MockLLMProvider, ProviderManager, OpenRouterProvider } from "@omnia/llm";
+import { GeminiProvider, ILLMProvider, MockLLMProvider, ProviderManager, OpenRouterProvider, IEmbeddingProvider, GeminiEmbeddingProvider, MockEmbeddingProvider, ModelProviderInstance } from "@omnia/llm";
 import { ScenarioLoader } from "@omnia/scenario";

 import type {
@@ -89,6 +89,7 @@ interface SimSession {
  dbPath: string;
  coreRepo: SQLiteRepository;
  bufferRepo: BufferRepository;
+  ledgerRepo: LedgerRepository;
  worldInstanceId: string;
  scenarioName: string;
  scenarioDescription: string;
@@ -101,6 +102,7 @@ interface SimSession {
  validatorProvider: ILLMProvider;
  decoderProvider: ILLMProvider;
  timedeltaProvider: ILLMProvider;
+  embeddingProvider: IEmbeddingProvider;
  architect: Architect;
  aliasGenerator: AliasDeltaGenerator;
  log: LogEntry[];
@@ -119,14 +121,14 @@ class SimulationManager {
    playEntityName?: string,
    providerInstanceId?: string,
  ): Promise<SimSnapshot> {
-    let activeInstance = providerInstanceId
-      ? ProviderManager.list().find((p) => p.id === providerInstanceId)
-      : ProviderManager.getActive();
+    let activeInstance: ModelProviderInstance | null = providerInstanceId
+      ? ProviderManager.list().find((p) => p.id === providerInstanceId) || null
+      : ProviderManager.getActive("generative");

    if (!activeInstance) {
      const envKey = process.env.GOOGLE_API_KEY;
      if (envKey) {
-        activeInstance = ProviderManager.create("Default (Env)", "google-genai", envKey);
+        activeInstance = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
      }
    }

@@ -154,6 +156,7 @@ class SimulationManager {
    const db = new Database(dbPath);
    const coreRepo = new SQLiteRepository(db);
    const bufferRepo = new BufferRepository(db);
+    const ledgerRepo = new LedgerRepository(db);
    const loader = new ScenarioLoader(coreRepo, bufferRepo);

    const worldInstanceId = id;
@@ -219,13 +222,13 @@ class SimulationManager {
    }

    const list = ProviderManager.list();
-    const active = ProviderManager.getActive() || activeInstance;
+    const active = ProviderManager.getActive("generative") || activeInstance;
    const mappings = ProviderManager.getMappings();

    const resolveProviderForTask = (task: string): ILLMProvider => {
      const mappedId = mappings[task];
      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-      if (!inst) {
+      if (!inst || inst.type !== "generative") {
        inst = active;
      }

@@ -242,10 +245,29 @@ class SimulationManager {
      }
    };

+    const resolveEmbeddingProvider = (): IEmbeddingProvider => {
+      const mappedId = mappings["embeddings"];
+      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+      if (!inst || inst.type !== "embedding") {
+        inst = ProviderManager.getActive("embedding");
+      }
+
+      const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
+      const providerName = inst ? inst.providerName : "google-genai";
+      const modelName = inst ? inst.modelName : undefined;
+
+      if (providerName === "google-genai") {
+        return new GeminiEmbeddingProvider(key, modelName);
+      } else {
+        return new MockEmbeddingProvider(modelName);
+      }
+    };
+
    const actorProvider = resolveProviderForTask("actor-prose");
    const validatorProvider = resolveProviderForTask("llm-validator");
    const decoderProvider = resolveProviderForTask("intent-decoder");
    const timedeltaProvider = resolveProviderForTask("timedelta");
+    const embeddingProvider = resolveEmbeddingProvider();

    const architect = new Architect(
      { validator: validatorProvider, timedelta: timedeltaProvider },
@@ -258,9 +280,10 @@ class SimulationManager {
      dbPath,
      coreRepo,
      bufferRepo,
-      worldInstanceId,
+      ledgerRepo,
+      worldInstanceId: worldInstanceId,
      scenarioName: scenarioJson.name,
-      scenarioDescription: scenarioJson.description,
+      scenarioDescription: scenarioJson.description || "",
      turn: 1,
      maxTurns: 20,
      entities: entityInfos,
@@ -270,6 +293,7 @@ class SimulationManager {
      validatorProvider,
      decoderProvider,
      timedeltaProvider,
+      embeddingProvider,
      architect,
      aliasGenerator,
      log: [],
@@ -353,6 +377,7 @@ class SimulationManager {
      const playerActor = new ActorAgent(
        { actor: session.actorProvider, decoder: session.decoderProvider },
        session.bufferRepo,
+        session.ledgerRepo,
        20,
        new FixedProseGenerator(prose),
      );
@@ -463,7 +488,7 @@ class SimulationManager {
    const entity = worldState.getEntity(info.id);
    if (!entity) throw new Error(`Entity "${info.id}" not found`);

-    const promptBuilder = new ActorPromptBuilder(session.bufferRepo, 20);
+    const promptBuilder = new ActorPromptBuilder(session.bufferRepo, session.ledgerRepo, 20);
    const { systemPrompt, userContext } = promptBuilder.build(
      worldState,
      entity,
@@ -493,6 +518,7 @@ class SimulationManager {
    const actor = new ActorAgent(
      { actor: session.actorProvider, decoder: session.decoderProvider },
      session.bufferRepo,
+      session.ledgerRepo,
      20,
    );
    const result = await actor.act(worldState, entity);
@@ -650,19 +676,19 @@ class SimulationManager {
      }

      const list = ProviderManager.list();
-      const active = ProviderManager.getActive();
+      const active = ProviderManager.getActive("generative");
      const mappings = state.providerMappings || {};

      const resolveProviderForTask = (task: string): ILLMProvider => {
        const mappedId = mappings[task];
        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-        if (!inst) {
+        if (!inst || inst.type !== "generative") {
          inst = active;
        }
        if (!inst) {
          const envKey = process.env.GOOGLE_API_KEY;
          if (envKey) {
-            inst = ProviderManager.create("Default (Env)", "google-genai", envKey);
+            inst = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
          }
        }

@@ -679,13 +705,39 @@ class SimulationManager {
        }
      };

+      const resolveEmbeddingProvider = (): IEmbeddingProvider => {
+        const mappedId = mappings["embeddings"];
+        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+        if (!inst || inst.type !== "embedding") {
+          inst = ProviderManager.getActive("embedding");
+        }
+        if (!inst) {
+          const envKey = process.env.GOOGLE_API_KEY;
+          if (envKey) {
+            inst = ProviderManager.create("Default Embed (Env)", "google-genai", envKey, "gemini-embedding-001", "embedding");
+          }
+        }
+
+        if (!inst) {
+          throw new Error(`No active Embedding Provider Instance found for task "embeddings". Please configure an embedding key in Settings first.`);
+        }
+
+        if (inst.providerName === "google-genai") {
+          return new GeminiEmbeddingProvider(inst.apiKey, inst.modelName);
+        } else {
+          return new MockEmbeddingProvider(inst.modelName);
+        }
+      };
+
      const coreRepo = new SQLiteRepository(db);
      const bufferRepo = new BufferRepository(db);
+      const ledgerRepo = new LedgerRepository(db);

      const actorProvider = resolveProviderForTask("actor-prose");
      const validatorProvider = resolveProviderForTask("llm-validator");
      const decoderProvider = resolveProviderForTask("intent-decoder");
      const timedeltaProvider = resolveProviderForTask("timedelta");
+      const embeddingProvider = resolveEmbeddingProvider();

      const architect = new Architect(
        { validator: validatorProvider, timedelta: timedeltaProvider },
@@ -698,6 +750,7 @@ class SimulationManager {
        dbPath,
        coreRepo,
        bufferRepo,
+        ledgerRepo,
        worldInstanceId: id,
        scenarioName: state.scenarioName,
        scenarioDescription: state.scenarioDescription,
@@ -710,6 +763,7 @@ class SimulationManager {
        validatorProvider,
        decoderProvider,
        timedeltaProvider,
+        embeddingProvider,
        architect,
        aliasGenerator,
        log: state.log || [],
@@ -777,6 +831,53 @@ class SimulationManager {
    });
  }

+  async regenerateAllEmbeddings(newProviderInstanceId?: string): Promise<void> {
+    const dbDir = path.resolve(process.cwd(), "data");
+    if (!fs.existsSync(dbDir)) return;
+
+    const files = fs.readdirSync(dbDir).filter(f => f.startsWith("sim-") && f.endsWith(".db"));
+
+    const list = ProviderManager.list();
+    let inst = newProviderInstanceId ? list.find((p) => p.id === newProviderInstanceId) : null;
+    if (!inst || inst.type !== "embedding") {
+      inst = ProviderManager.getActive("embedding");
+    }
+
+    const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
+    const providerName = inst ? inst.providerName : "google-genai";
+    const modelName = inst ? inst.modelName : undefined;
+
+    let embeddingProvider: IEmbeddingProvider;
+    if (providerName === "google-genai") {
+      embeddingProvider = new GeminiEmbeddingProvider(key, modelName);
+    } else {
+      embeddingProvider = new MockEmbeddingProvider(modelName);
+    }
+
+    for (const file of files) {
+      const dbPath = path.join(dbDir, file);
+      const id = file.replace(".db", "");
+      const activeSession = this.sessions.get(id);
+      const db = activeSession ? activeSession.db : new Database(dbPath);
+
+      try {
+        const rows = db.prepare(`SELECT id, content FROM ledger_entries`).all() as { id: string; content: string }[];
+        
+        for (const row of rows) {
+          const vector = await embeddingProvider.embed(row.content);
+          const buffer = Buffer.from(new Float32Array(vector).buffer);
+          db.prepare(`UPDATE ledger_entries SET embedding = ? WHERE id = ?`).run(buffer, row.id);
+        }
+      } catch (err) {
+        console.error(`Failed to regenerate embeddings for ${file}:`, err);
+      } finally {
+        if (!activeSession) {
+          db.close();
+        }
+      }
+    }
+  }
+
  private save(session: SimSession): void {
    const state: SavedState = {
      scenarioName: session.scenarioName,
--- a/packages/actor/src/actor-prompt-builder.ts
+++ b/packages/actor/src/actor-prompt-builder.ts
@@ -9,6 +9,8 @@ import {
  BufferEntry,
  BufferRepository,
  serializeSubjectiveBufferEntry,
+  LedgerEntry,
+  LedgerRepository,
 } from "@omnia/memory";

 /**
@@ -37,12 +39,17 @@ export class ActorPromptBuilder {
  /**
   * @param bufferRepo  Used to fetch the actor's recent memory. Optional —
   *                    if absent, the memory section is omitted.
+   * @param ledgerRepo  Used to fetch long-term memories. Optional.
   * @param memoryLimit Maximum number of recent buffer entries to inject.
   *                    Defaults to 20.
+   * @param ledgerLimit Maximum number of long-term memories to retrieve.
+   *                    Defaults to 5.
   */
  constructor(
    private bufferRepo?: BufferRepository,
+    private ledgerRepo?: LedgerRepository,
    private memoryLimit = 20,
+    private ledgerLimit = 5,
  ) {}

  /**
@@ -74,15 +81,14 @@ Guidelines:
 - Keep your prose vivid but concise. A single response may contain more than one intent (e.g., you may think, then speak, then act) — write them in natural narrative order.
 - Not every response requires an outward action. It is perfectly valid to only think (a monologue) and do nothing perceivable.
 - Never speak or act on another entity's behalf — you only control your own character.
-".
 `.trim();
  }

  private buildUserContext(worldState: WorldState, entity: Entity): string {
    const sections: string[] = [];
+    const now = worldState.clock.get();

    // --- Subjective present time ---
-    const now = worldState.clock.get();
    sections.push(
      `=== CURRENT MOMENT ===\nIt is ${now.toISOString()} right now.`,
    );
@@ -92,30 +98,43 @@ Guidelines:
      `=== THE WORLD AS YOU PERCEIVE IT ===\n${serializeSubjectiveWorldState(worldState, entity.id)}`,
    );

+    // Fetch recent buffer entries once
+    let recentEntries: BufferEntry[] = [];
+    if (this.bufferRepo) {
+      try {
+        recentEntries = this.bufferRepo.listForOwner(entity.id);
+      } catch {}
+    }
+
    // --- Recent memory ---
-    const memorySection = this.buildMemorySection(
-      entity,
-      worldState.clock.get(),
-    );
+    const memorySection = this.buildMemorySection(entity, recentEntries, now);
    if (memorySection) {
      sections.push(memorySection);
    }

+    // --- Recalled Long-Term memory ---
+    const ledgerSection = this.buildLedgerSection(
+      worldState,
+      entity,
+      recentEntries,
+      now,
+    );
+    if (ledgerSection) {
+      sections.push(ledgerSection);
+    }
+
    return sections.join("\n\n");
  }

-  private buildMemorySection(entity: Entity, now: Date): string | null {
+  private buildMemorySection(
+    entity: Entity,
+    entries: BufferEntry[],
+    now: Date,
+  ): string | null {
    if (!this.bufferRepo) return null;

-    let entries: BufferEntry[];
-    try {
-      entries = this.bufferRepo.listForOwner(entity.id);
-    } catch {
-      return null;
-    }
-
    if (entries.length === 0) {
-      return `=== YOUR RECENT MEMORY ===\n(You have no memories yet.)`;
+      return `=== RECENT EVENTS ===\n(No recent events recorded.)`;
    }

    const recent = entries.slice(-this.memoryLimit);
@@ -135,6 +154,110 @@ Guidelines:
      groupedLines.push(`  - ${serialized}`);
    }

-    return `=== YOUR RECENT MEMORY ===\n${groupedLines.join("\n")}`;
+    return `=== RECENT EVENTS ===\n${groupedLines.join("\n")}`;
+  }
+
+  private buildLedgerSection(
+    worldState: WorldState,
+    entity: Entity,
+    recentBuffer: BufferEntry[],
+    now: Date,
+  ): string | null {
+    if (!this.ledgerRepo) return null;
+
+    // 1. Get co-located entities (in the same location as entity)
+    const coLocatedEntityIds: string[] = [];
+    if (entity.locationId) {
+      for (const e of worldState.entities.values()) {
+        if (e.id !== entity.id && e.locationId === entity.locationId) {
+          coLocatedEntityIds.push(e.id);
+        }
+      }
+    }
+
+    // 2. Compute Active Focus entities based on recent interactions (last 10 entries)
+    const activeFocus = new Set<string>();
+    const maxFocus = 3;
+
+    // We scan the recent buffer entries to see who we recently talked to or who talked to us
+    for (let i = recentBuffer.length - 1; i >= 0; i--) {
+      const entry = recentBuffer[i];
+      const intent = entry.intent;
+
+      if (
+        intent.actorId !== entity.id &&
+        coLocatedEntityIds.includes(intent.actorId)
+      ) {
+        activeFocus.add(intent.actorId);
+      }
+      for (const targetId of intent.targetIds) {
+        if (targetId !== entity.id && coLocatedEntityIds.includes(targetId)) {
+          activeFocus.add(targetId);
+        }
+      }
+      if (activeFocus.size >= maxFocus) break;
+    }
+
+    // If co-located entities is small, auto-focus all of them
+    if (activeFocus.size < maxFocus && coLocatedEntityIds.length <= maxFocus) {
+      for (const id of coLocatedEntityIds) {
+        if (id !== entity.id) {
+          activeFocus.add(id);
+        }
+      }
+    }
+
+    const activeFocusIds = Array.from(activeFocus);
+
+    // 3. Retrieve memories using Active Focus
+    let recalled: LedgerEntry[];
+    try {
+      recalled = this.ledgerRepo.retrieve(
+        entity.id,
+        entity.locationId,
+        activeFocusIds,
+        undefined, // no query embedding for now (Recency + Importance ranking)
+        now,
+        this.ledgerLimit,
+        { includeAssociativeNeighbors: true },
+      );
+    } catch {
+      return null;
+    }
+
+    if (recalled.length === 0) return null;
+
+    // 4. Format them identical to the recent memory format
+    const groupedLines: string[] = [];
+    let currentGroup: string | null = null;
+
+    for (const entry of recalled) {
+      const when = naturalizeTime(now, new Date(entry.timestamp));
+
+      let content = entry.content;
+      // Resolve system IDs to subjective aliases in the content
+      for (const targetId of entry.involvedEntityIds) {
+        const alias = entity.aliases.get(targetId) ?? targetId;
+        content = content.replace(new RegExp(targetId, "g"), alias);
+      }
+      if (entry.locationId) {
+        content += ` (at ${entry.locationId})`;
+      }
+
+      if (when !== currentGroup) {
+        currentGroup = when;
+        const header = when.charAt(0).toUpperCase() + when.slice(1);
+        groupedLines.push(header);
+      }
+
+      groupedLines.push(`  - ${content}`);
+      if (entry.quotes && entry.quotes.length > 0) {
+        for (const quote of entry.quotes) {
+          groupedLines.push(`    Quote: "${quote}"`);
+        }
+      }
+    }
+
+    return `=== YOUR MEMORIES ===\n${groupedLines.join("\n")}`;
  }
 }
--- a/packages/actor/src/actor.ts
+++ b/packages/actor/src/actor.ts
@@ -3,6 +3,7 @@ import { ILLMProvider } from "@omnia/llm";
 import {
  BufferEntry,
  BufferRepository,
+  LedgerRepository,
 } from "@omnia/memory";
 import {
  Intent,
@@ -73,6 +74,7 @@ export class ActorAgent {
  constructor(
    llmProvider: ILLMProvider | { actor: ILLMProvider; decoder: ILLMProvider },
    bufferRepo?: BufferRepository,
+    ledgerRepo?: LedgerRepository,
    memoryLimit?: number,
    generator?: IActorProseGenerator,
  ) {
@@ -87,7 +89,7 @@ export class ActorAgent {
      decoderProv = llmProvider;
    }

-    this.promptBuilder = new ActorPromptBuilder(bufferRepo, memoryLimit);
+    this.promptBuilder = new ActorPromptBuilder(bufferRepo, ledgerRepo, memoryLimit);
    this.decoder = new IntentDecoder(decoderProv);
    this.generator = generator ?? new LLMActorProseGenerator(actorProv);
    this.llmProvider = actorProv;
--- a/packages/actor/tests/actor-prompt-builder.test.ts
+++ b/packages/actor/tests/actor-prompt-builder.test.ts
@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { WorldState, Entity, AttributeVisibility } from "@omnia/core";
+import { BufferRepository, LedgerRepository } from "@omnia/memory";
+import { ActorPromptBuilder } from "../src/actor-prompt-builder";
+
+describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
+  let db: Database.Database;
+  let bufferRepo: BufferRepository;
+  let ledgerRepo: LedgerRepository;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    
+    // Core database schemas for testing
+    db.exec(`
+      CREATE TABLE objects (
+        id TEXT PRIMARY KEY
+      );
+    `);
+
+    db.exec(`
+      INSERT INTO objects (id) VALUES ('alice'), ('bob'), ('charlie');
+    `);
+
+    bufferRepo = new BufferRepository(db);
+    ledgerRepo = new LedgerRepository(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it("should inject both recent memory and recalled long-term memory with subjective aliases resolved", () => {
+    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
+    
+    const alice = new Entity("alice", "tavern");
+    // Add subjective alias for bob
+    alice.aliases.set("bob", "Strider");
+    world.addEntity(alice);
+
+    const bob = new Entity("bob", "tavern");
+    world.addEntity(bob);
+
+    // 1. Populate recent buffer memory
+    bufferRepo.save({
+      id: "buf1",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:58:00.000Z", // 2 mins ago
+      locationId: "tavern",
+      intent: {
+        type: "dialogue",
+        actorId: "alice",
+        targetIds: ["bob"],
+        originalText: "Hello there",
+        description: "Alice greets Bob",
+      },
+    });
+
+    // 2. Populate ledger repository (long-term memory)
+    ledgerRepo.save({
+      id: "ledger1",
+      ownerId: "alice",
+      timestamp: "2024-01-08T12:00:00.000Z", // 2 days ago
+      locationId: "tavern",
+      involvedEntityIds: ["bob"],
+      content: "alice met bob at the tavern.",
+      quotes: ["I am a ranger."],
+      importance: 9,
+      embedding: [],
+    });
+
+    const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
+    const { userContext } = builder.build(world, alice);
+
+    // Check recent memory exists
+    expect(userContext).toContain("=== RECENT EVENTS ===");
+    expect(userContext).toContain("Alice greets Bob");
+    // Bob should be resolved to Strider
+    expect(userContext).toContain("spoke to Strider");
+
+    // Check long-term memory exists
+    expect(userContext).toContain("=== YOUR MEMORIES ===");
+    // Bob should be resolved to Strider in the ledger content
+    expect(userContext).toContain("alice met Strider at the tavern.");
+    expect(userContext).toContain('Quote: "I am a ranger."');
+  });
+
+  it("should not explode if ledger contains no memories or is empty", () => {
+    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
+    const alice = new Entity("alice", "tavern");
+    world.addEntity(alice);
+
+    const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
+    const { userContext } = builder.build(world, alice);
+
+    expect(userContext).toContain("=== RECENT EVENTS ===");
+    expect(userContext).not.toContain("=== YOUR MEMORIES ===");
+  });
+});
--- a/packages/llm/src/llm.ts
+++ b/packages/llm/src/llm.ts
@@ -30,46 +30,55 @@ export interface LLMCallRecord {

 export interface ILLMProvider {
  providerName: string;
-  // We use Zod to ensure the generic T matches the schema
  generateStructuredResponse<T extends z.ZodTypeAny>(
    request: LLMRequest<T>,
  ): Promise<LLMResponse<z.infer<T>>>;
  lastCalls?: LLMCallRecord[];
 }

-export interface LLMProviderInstance {
+export interface IEmbeddingProvider {
+  providerName: string;
+  embed(text: string): Promise<number[]>;
+}
+
+export interface ModelProviderInstance {
  id: string;
  name: string;
  providerName: string;
  apiKey: string;
  isActive: boolean;
  modelName?: string;
+  type: "generative" | "embedding";
 }

-export interface LLMProviderMeta {
+export interface ModelProviderMeta {
  id: string;
  displayName: string;
  description: string;
  defaultModel: string;
+  defaultEmbeddingModel: string;
 }

-export const AVAILABLE_PROVIDERS: LLMProviderMeta[] = [
+export const AVAILABLE_PROVIDERS: ModelProviderMeta[] = [
  {
    id: "google-genai",
    displayName: "Google Gemini",
    description: "Official Gemini integration using Google Gen AI SDK",
    defaultModel: "gemini-2.5-flash",
+    defaultEmbeddingModel: "gemini-embedding-001",
  },
  {
    id: "openrouter",
    displayName: "OpenRouter",
    description: "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models",
    defaultModel: "google/gemini-2.5-flash",
+    defaultEmbeddingModel: "openai/text-embedding-3-small",
  },
  {
    id: "mock",
    displayName: "Mock LLM Provider",
    description: "Stateless mock provider for testing and offline development",
    defaultModel: "mock",
+    defaultEmbeddingModel: "mock-embeddings",
  },
 ];
--- a/packages/llm/src/provider-manager.ts
+++ b/packages/llm/src/provider-manager.ts
@@ -1,7 +1,7 @@
 import Database from "better-sqlite3";
 import path from "path";
 import fs from "fs";
-import type { LLMProviderInstance } from "./llm.js";
+import type { ModelProviderInstance } from "./llm.js";

 function getWorkspaceRoot() {
  let current = process.cwd();
@@ -35,7 +35,8 @@ function getSettingsDb() {
      providerName TEXT NOT NULL,
      apiKey TEXT NOT NULL,
      isActive INTEGER NOT NULL DEFAULT 0,
-      modelName TEXT
+      modelName TEXT,
+      type TEXT NOT NULL DEFAULT 'generative'
    )
  `).run();

@@ -44,12 +45,18 @@ function getSettingsDb() {
  } catch {
    // ignore
  }
+
+  try {
+    db.prepare(`ALTER TABLE provider_instances ADD COLUMN type TEXT NOT NULL DEFAULT 'generative'`).run();
+  } catch {
+    // ignore
+  }
  
  return db;
 }

 export class ProviderManager {
-  static list(): LLMProviderInstance[] {
+  static list(): ModelProviderInstance[] {
    const db = getSettingsDb();
    try {
      const rows = db.prepare(`SELECT * FROM provider_instances`).all() as {
@@ -59,6 +66,7 @@ export class ProviderManager {
        apiKey: string;
        isActive: number;
        modelName?: string;
+        type: string;
      }[];
      return rows.map((r) => ({
        id: r.id,
@@ -67,25 +75,34 @@ export class ProviderManager {
        apiKey: r.apiKey,
        isActive: r.isActive === 1,
        modelName: r.modelName || undefined,
+        type: (r.type as "generative" | "embedding") || "generative",
      }));
    } finally {
      db.close();
    }
  }

-  static create(name: string, providerName: string, apiKey: string, modelName?: string): LLMProviderInstance {
+  static create(
+    name: string,
+    providerName: string,
+    apiKey: string,
+    modelName?: string,
+    type: "generative" | "embedding" = "generative"
+  ): ModelProviderInstance {
    const db = getSettingsDb();
    try {
      const id = "provider-" + Date.now();
-      const activeCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances WHERE isActive = 1`).get() as { count: number };
+      const activeCount = db
+        .prepare(`SELECT COUNT(*) as count FROM provider_instances WHERE isActive = 1 AND type = ?`)
+        .get(type) as { count: number };
      const isActive = activeCount.count === 0 ? 1 : 0;
      
      db.prepare(`
-        INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName)
-        VALUES (?, ?, ?, ?, ?, ?)
-      `).run(id, name, providerName, apiKey, isActive, modelName || null);
+        INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(id, name, providerName, apiKey, isActive, modelName || null, type);
      
-      return { id, name, providerName, apiKey, isActive: isActive === 1, modelName };
+      return { id, name, providerName, apiKey, isActive: isActive === 1, modelName, type };
    } finally {
      db.close();
    }
@@ -94,11 +111,13 @@ export class ProviderManager {
  static delete(id: string): void {
    const db = getSettingsDb();
    try {
-      const provider = db.prepare(`SELECT isActive FROM provider_instances WHERE id = ?`).get(id) as { isActive: number } | undefined;
+      const provider = db.prepare(`SELECT isActive, type FROM provider_instances WHERE id = ?`).get(id) as { isActive: number; type: string } | undefined;
      db.prepare(`DELETE FROM provider_instances WHERE id = ?`).run(id);
      
      if (provider && provider.isActive === 1) {
-        const next = db.prepare(`SELECT id FROM provider_instances LIMIT 1`).get() as { id: string } | undefined;
+        const next = db
+          .prepare(`SELECT id FROM provider_instances WHERE type = ? LIMIT 1`)
+          .get(provider.type) as { id: string } | undefined;
        if (next) {
          db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(next.id);
        }
@@ -111,60 +130,85 @@ export class ProviderManager {
  static setActive(id: string): void {
    const db = getSettingsDb();
    try {
-      db.prepare(`UPDATE provider_instances SET isActive = 0`).run();
-      db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(id);
-    } finally {
-      db.close();
-    }
-  }
-
-  static update(id: string, name: string, providerName: string, apiKey?: string, modelName?: string): void {
-    const db = getSettingsDb();
-    try {
-      if (apiKey && apiKey.trim()) {
-        db.prepare(`
-          UPDATE provider_instances
-          SET name = ?, providerName = ?, apiKey = ?, modelName = ?
-          WHERE id = ?
-        `).run(name, providerName, apiKey, modelName || null, id);
-      } else {
-        db.prepare(`
-          UPDATE provider_instances
-          SET name = ?, providerName = ?, modelName = ?
-          WHERE id = ?
-        `).run(name, providerName, modelName || null, id);
+      const target = db.prepare(`SELECT type FROM provider_instances WHERE id = ?`).get(id) as { type: string } | undefined;
+      if (target) {
+        db.prepare(`UPDATE provider_instances SET isActive = 0 WHERE type = ?`).run(target.type);
+        db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(id);
      }
    } finally {
      db.close();
    }
  }

-  static getActive(): LLMProviderInstance | null {
+  static update(
+    id: string,
+    name: string,
+    providerName: string,
+    apiKey?: string,
+    modelName?: string,
+    type: "generative" | "embedding" = "generative"
+  ): void {
    const db = getSettingsDb();
    try {
-      // Query the DB
-      const row = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1`).get() as {
+      if (apiKey && apiKey.trim()) {
+        db.prepare(`
+          UPDATE provider_instances
+          SET name = ?, providerName = ?, apiKey = ?, modelName = ?, type = ?
+          WHERE id = ?
+        `).run(name, providerName, apiKey, modelName || null, type, id);
+      } else {
+        db.prepare(`
+          UPDATE provider_instances
+          SET name = ?, providerName = ?, modelName = ?, type = ?
+          WHERE id = ?
+        `).run(name, providerName, modelName || null, type, id);
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  static getActive(type: "generative" | "embedding" = "generative"): ModelProviderInstance | null {
+    const db = getSettingsDb();
+    try {
+      const row = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?`).get(type) as {
        id: string;
        name: string;
        providerName: string;
        apiKey: string;
        isActive: number;
        modelName?: string;
+        type: string;
      } | undefined;

      if (!row) {
-        // Check if there are any rows at all
        const totalCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances`).get() as { count: number };
        if (totalCount.count === 0) {
-          // Database is completely empty! Check if GOOGLE_API_KEY env is set.
          const envKey = process.env.GOOGLE_API_KEY;
          if (envKey && envKey.trim()) {
-            // Auto-bootstrap default active instance from env
            const id = "provider-default-env";
            db.prepare(`
-              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName)
-              VALUES (?, ?, ?, ?, ?, ?)
-            `).run(id, "Default (Env)", "google-genai", envKey, 1, "gemini-2.5-flash");
+              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type)
+              VALUES (?, ?, ?, ?, ?, ?, ?)
+            `).run(id, "Default (Env)", "google-genai", envKey, 1, "gemini-2.5-flash", "generative");
+
+            const embedId = "provider-default-env-embed";
+            db.prepare(`
+              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type)
+              VALUES (?, ?, ?, ?, ?, ?, ?)
+            `).run(embedId, "Default Embed (Env)", "google-genai", envKey, 1, "gemini-embedding-001", "embedding");
+
+            if (type === "embedding") {
+              return {
+                id: embedId,
+                name: "Default Embed (Env)",
+                providerName: "google-genai",
+                apiKey: envKey,
+                isActive: true,
+                modelName: "gemini-embedding-001",
+                type: "embedding",
+              };
+            }

            return {
              id,
@@ -173,6 +217,7 @@ export class ProviderManager {
              apiKey: envKey,
              isActive: true,
              modelName: "gemini-2.5-flash",
+              type: "generative",
            };
          }
        }
@@ -186,11 +231,22 @@ export class ProviderManager {
        apiKey: row.apiKey,
        isActive: true,
        modelName: row.modelName || undefined,
+        type: (row.type as "generative" | "embedding") || "generative",
      };
    } catch {
-      // Lock or write issue fallback: return an in-memory active key if env key exists
      const envKey = process.env.GOOGLE_API_KEY;
      if (envKey) {
+        if (type === "embedding") {
+          return {
+            id: "provider-default-env-embed-fallback",
+            name: "Default Embed (Env Fallback)",
+            providerName: "google-genai",
+            apiKey: envKey,
+            isActive: true,
+            modelName: "gemini-embedding-001",
+            type: "embedding",
+          };
+        }
        return {
          id: "provider-default-env-fallback",
          name: "Default (Env Fallback)",
@@ -198,6 +254,7 @@ export class ProviderManager {
          apiKey: envKey,
          isActive: true,
          modelName: "gemini-2.5-flash",
+          type: "generative",
        };
      }
      return null;
--- a/packages/llm/src/providers/google-genai.ts
+++ b/packages/llm/src/providers/google-genai.ts
@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
-import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord } from "../llm.js";
+import { ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";
 import { llmConfig } from "../config.js";
 import { ProviderManager } from "../provider-manager.js";

@@ -19,7 +19,7 @@ export class GeminiProvider implements ILLMProvider {
    let model = modelName;

    if (!key) {
-      const active = ProviderManager.getActive();
+      const active = ProviderManager.getActive("generative");
      if (active) {
        key = active.apiKey;
        if (!model) {
@@ -78,3 +78,43 @@ export class GeminiProvider implements ILLMProvider {
    return { success: true, data: parsed, usage };
  }
 }
+
+export class GeminiEmbeddingProvider implements IEmbeddingProvider {
+  static readonly providerId = "google-genai";
+  static readonly displayName = "Google Gemini Embeddings";
+
+  providerName = "Gemini";
+  private model: GoogleGenerativeAIEmbeddings;
+
+  constructor(apiKey?: string, modelName?: string) {
+    let key = apiKey;
+    let model = modelName;
+
+    if (!key) {
+      const active = ProviderManager.getActive("embedding");
+      if (active) {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+      }
+    }
+
+    if (!key) {
+      key = llmConfig.GOOGLE_API_KEY;
+    }
+
+    if (!key) {
+      throw new Error("GOOGLE_API_KEY is required to initialize GeminiEmbeddingProvider");
+    }
+
+    this.model = new GoogleGenerativeAIEmbeddings({
+      apiKey: key,
+      modelName: model || "gemini-embedding-001",
+    });
+  }
+
+  async embed(text: string): Promise<number[]> {
+    return this.model.embedQuery(text);
+  }
+}
--- a/packages/llm/src/providers/mock.ts
+++ b/packages/llm/src/providers/mock.ts
@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord } from "../llm.js";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";

 export class MockLLMProvider implements ILLMProvider {
  static readonly providerId = "mock";
@@ -34,3 +34,21 @@ export class MockLLMProvider implements ILLMProvider {
    }
  }
 }
+
+export class MockEmbeddingProvider implements IEmbeddingProvider {
+  static readonly providerId = "mock";
+
+  providerName = "mock";
+
+  constructor(private modelName?: string) {}
+
+  async embed(text: string): Promise<number[]> {
+    // Return a deterministic mock 768-dimensional vector based on the text
+    const vec = new Array(768).fill(0).map((_, i) => {
+      // Return a predictable float between -1.0 and 1.0
+      const charCode = text.charCodeAt(i % text.length) || 0;
+      return Math.sin(charCode + i);
+    });
+    return vec;
+  }
+}
--- a/packages/llm/src/providers/openrouter.ts
+++ b/packages/llm/src/providers/openrouter.ts
@@ -19,7 +19,7 @@ export class OpenRouterProvider implements ILLMProvider {
    let model = modelName;

    if (!key) {
-      const active = ProviderManager.getActive();
+      const active = ProviderManager.getActive("generative");
      if (active) {
        key = active.apiKey;
        if (!model) {
--- a/packages/llm/tests/mock.test.ts
+++ b/packages/llm/tests/mock.test.ts
@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { z } from "zod";
-import { MockLLMProvider } from "@omnia/llm";
+import { MockLLMProvider, MockEmbeddingProvider } from "@omnia/llm";

 describe("MockLLMProvider Unit Tests (Tier 1)", () => {
  test("returns parsed matching data for valid mock response", async () => {
@@ -61,3 +61,21 @@ describe("MockLLMProvider Unit Tests (Tier 1)", () => {
    expect(response.data).toBeUndefined();
  });
 });
+
+describe("MockEmbeddingProvider Unit Tests (Tier 1)", () => {
+  test("generates deterministic 768-dimensional vectors", async () => {
+    const provider = new MockEmbeddingProvider("mock-embeddings");
+    const text = "Hello world";
+    const vec1 = await provider.embed(text);
+    const vec2 = await provider.embed(text);
+
+    expect(vec1.length).toBe(768);
+    expect(vec2.length).toBe(768);
+    expect(vec1).toEqual(vec2); // Deterministic
+    
+    // Ensure values are numbers between -1.0 and 1.0 (since they are generated with Math.sin)
+    expect(typeof vec1[0]).toBe("number");
+    expect(vec1[0]).toBeGreaterThanOrEqual(-1.0);
+    expect(vec1[0]).toBeLessThanOrEqual(1.0);
+  });
+});
--- a/packages/memory/src/ledger.ts
+++ b/packages/memory/src/ledger.ts
@@ -92,6 +92,31 @@ export class LedgerRepository {
    })();
  }

+  private mapRowToEntry(row: any, involvedEntityIds: string[]): LedgerEntry {
+    let embedding: number[] = [];
+    if (row.embedding) {
+      const buffer = row.embedding as Buffer;
+      const floatArray = new Float32Array(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength / Float32Array.BYTES_PER_ELEMENT
+      );
+      embedding = Array.from(floatArray);
+    }
+
+    return {
+      id: row.id,
+      ownerId: row.owner_id,
+      timestamp: row.timestamp,
+      locationId: row.location_id,
+      involvedEntityIds,
+      content: row.content,
+      quotes: JSON.parse(row.quotes_json || "[]"),
+      importance: row.importance,
+      embedding: embedding,
+    };
+  }
+
  load(id: string): LedgerEntry | null {
    const row = this.db
      .prepare(
@@ -113,28 +138,7 @@ export class LedgerRepository {
      )
      .all(id) as { entity_id: string }[];

-    let embedding: number[] = [];
-    if (row.embedding) {
-      const buffer = row.embedding as Buffer;
-      const floatArray = new Float32Array(
-        buffer.buffer,
-        buffer.byteOffset,
-        buffer.byteLength / Float32Array.BYTES_PER_ELEMENT
-      );
-      embedding = Array.from(floatArray);
-    }
-
-    return {
-      id: row.id,
-      ownerId: row.owner_id,
-      timestamp: row.timestamp,
-      locationId: row.location_id,
-      involvedEntityIds: entitiesRows.map((er) => er.entity_id),
-      content: row.content,
-      quotes: JSON.parse(row.quotes_json),
-      importance: row.importance,
-      embedding: embedding,
-    };
+    return this.mapRowToEntry(row, entitiesRows.map((er) => er.entity_id));
  }

  /**
@@ -202,32 +206,174 @@ export class LedgerRepository {
      entitiesMap.get(er.entry_id)!.push(er.entity_id);
    }

-    return rows.map((row) => {
-      let embedding: number[] = [];
-      if (row.embedding) {
-        const buffer = row.embedding as Buffer;
-        const floatArray = new Float32Array(
-          buffer.buffer,
-          buffer.byteOffset,
-          buffer.byteLength / Float32Array.BYTES_PER_ELEMENT
-        );
-        embedding = Array.from(floatArray);
+    return rows.map((row) => this.mapRowToEntry(row, entitiesMap.get(row.id) || []));
+  }
+
+  private fetchRawNeighbors(ownerId: string, timestamp: string): LedgerEntry[] {
+    const neighbors: LedgerEntry[] = [];
+
+    // Preceding entry
+    const preceding = this.db
+      .prepare(
+        `
+      SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
+      FROM ledger_entries
+      WHERE owner_id = ? AND timestamp < ?
+      ORDER BY timestamp DESC
+      LIMIT 1
+    `
+      )
+      .get(ownerId, timestamp) as any;
+
+    if (preceding) {
+      neighbors.push(this.mapRowToEntry(preceding, []));
+    }
+
+    // Succeeding entry
+    const succeeding = this.db
+      .prepare(
+        `
+      SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
+      FROM ledger_entries
+      WHERE owner_id = ? AND timestamp > ?
+      ORDER BY timestamp ASC
+      LIMIT 1
+    `
+      )
+      .get(ownerId, timestamp) as any;
+
+    if (succeeding) {
+      neighbors.push(this.mapRowToEntry(succeeding, []));
+    }
+
+    return neighbors;
+  }
+
+  /**
+   * Phase 1 + Phase 2 Retrieval Pipeline
+   * 1. Fetches candidates via Phase 1 heuristic filtering.
+   * 2. Ranks them using: Score = Recency + Importance + Semantic Match.
+   * 3. Selects the top `limit` memories.
+   * 4. Optionally pulls in the immediate chronological neighbors (associative chain).
+   * 5. Returns all gathered entries sorted chronologically (timestamp ASC).
+   */
+  retrieve(
+    ownerId: string,
+    currentLocationId: string | null,
+    currentInvolvedEntityIds: string[],
+    queryEmbedding?: number[],
+    now: Date = new Date(),
+    limit: number = 5,
+    options?: {
+      includeAssociativeNeighbors?: boolean;
+      recencyWeight?: number;
+      importanceWeight?: number;
+      relevanceWeight?: number;
+      decayRate?: number;
+    }
+  ): LedgerEntry[] {
+    const includeAssociativeNeighbors = options?.includeAssociativeNeighbors ?? false;
+    const recencyWeight = options?.recencyWeight ?? 1.0;
+    const importanceWeight = options?.importanceWeight ?? 1.0;
+    const relevanceWeight = options?.relevanceWeight ?? 1.0;
+    const decayRate = options?.decayRate ?? 0.99;
+
+    // Fetch candidate pool (limit 100 to provide enough options for Phase 2 ranking)
+    const candidates = this.getRelevant(ownerId, currentLocationId, currentInvolvedEntityIds, 100);
+    if (candidates.length === 0) return [];
+
+    // Score candidates
+    const scored = candidates.map((entry) => {
+      // Recency calculation with exponential decay
+      const deltaMs = now.getTime() - new Date(entry.timestamp).getTime();
+      const hoursElapsed = Math.max(0, deltaMs / (3600 * 1000));
+      const recency = Math.pow(decayRate, hoursElapsed);
+
+      // Importance score normalized (0.0 to 1.0)
+      const importanceNorm = entry.importance / 10.0;
+
+      // Semantic relevance
+      let relevance = 0;
+      if (queryEmbedding && entry.embedding && entry.embedding.length > 0) {
+        relevance = cosineSimilarity(queryEmbedding, entry.embedding);
      }
-      return {
-        id: row.id,
-        ownerId: row.owner_id,
-        timestamp: row.timestamp,
-        locationId: row.location_id,
-        involvedEntityIds: entitiesMap.get(row.id) || [],
-        content: row.content,
-        quotes: JSON.parse(row.quotes_json),
-        importance: row.importance,
-        embedding: embedding,
-      };
+
+      const score =
+        recencyWeight * recency +
+        importanceWeight * importanceNorm +
+        relevanceWeight * relevance;
+
+      return { entry, score };
    });
+
+    // Rank and take top memories
+    scored.sort((a, b) => b.score - a.score);
+    const selected = scored.slice(0, limit).map((s) => s.entry);
+
+    let finalEntries = [...selected];
+
+    // Optionally retrieve associative neighbors
+    if (includeAssociativeNeighbors && selected.length > 0) {
+      const neighborMap = new Map<string, LedgerEntry>();
+
+      for (const entry of selected) {
+        const rawNeighbors = this.fetchRawNeighbors(ownerId, entry.timestamp);
+        for (const rn of rawNeighbors) {
+          if (!finalEntries.some((fe) => fe.id === rn.id) && !neighborMap.has(rn.id)) {
+            neighborMap.set(rn.id, rn);
+          }
+        }
+      }
+
+      const neighborsToPopulate = Array.from(neighborMap.values());
+      if (neighborsToPopulate.length > 0) {
+        const neighborIds = neighborsToPopulate.map((n) => n.id);
+        const placeholders = neighborIds.map(() => "?").join(",");
+        const entitiesRows = this.db
+          .prepare(
+            `
+          SELECT entry_id, entity_id FROM ledger_involved_entities
+          WHERE entry_id IN (${placeholders})
+        `
+          )
+          .all(...neighborIds) as { entry_id: string; entity_id: string }[];
+
+        const entitiesMap = new Map<string, string[]>();
+        for (const er of entitiesRows) {
+          if (!entitiesMap.has(er.entry_id)) {
+            entitiesMap.set(er.entry_id, []);
+          }
+          entitiesMap.get(er.entry_id)!.push(er.entity_id);
+        }
+
+        for (const n of neighborsToPopulate) {
+          n.involvedEntityIds = entitiesMap.get(n.id) || [];
+          finalEntries.push(n);
+        }
+      }
+    }
+
+    // Sort chronologically ASC for the final prompt output
+    finalEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+
+    return finalEntries;
  }

  delete(id: string): void {
    this.db.prepare(`DELETE FROM ledger_entries WHERE id = ?`).run(id);
  }
 }
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
--- a/packages/memory/tests/ledger.test.ts
+++ b/packages/memory/tests/ledger.test.ts
@@ -121,4 +121,108 @@ describe("LedgerRepository", () => {
    expect(ids).toContain("mem_social"); // due to involvedEntityIds
    expect(ids).not.toContain("mem_irrelevant");
  });
+
+  it("should retrieve ranked memories with recency, importance, and semantic match", () => {
+    const now = new Date("2024-01-10T12:00:00.000Z");
+
+    repo.save({
+      id: "mem1",
+      ownerId: "alice",
+      timestamp: "2024-01-01T12:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice fought a dragon.",
+      quotes: [],
+      importance: 10,
+      embedding: [0, 1, 0],
+    });
+
+    repo.save({
+      id: "mem2",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice ate a sandwich.",
+      quotes: [],
+      importance: 2,
+      embedding: [1, 0, 0],
+    });
+
+    repo.save({
+      id: "mem3",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:50:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice read a book.",
+      quotes: [],
+      importance: 5,
+      embedding: [0.707, 0.707, 0],
+    });
+
+    // Query: [1, 0, 0]
+    // mem3 score: recency (~0.998) + importance (0.5) + relevance (0.707) = ~2.205
+    // mem2 score: recency (~0.99) + importance (0.2) + relevance (1.0) = ~2.19
+    // mem1 score: recency (~0.114) + importance (1.0) + relevance (0.0) = ~1.114
+    // If limit = 2, should return mem2 and mem3, sorted chronologically (mem2 first, then mem3)
+    const results = repo.retrieve("alice", "loc1", [], [1, 0, 0], now, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].id).toBe("mem2");
+    expect(results[1].id).toBe("mem3");
+  });
+
+  it("should pull in associative neighbors when specified", () => {
+    repo.save({
+      id: "mem_preceding",
+      ownerId: "alice",
+      timestamp: "2024-01-10T10:00:00.000Z",
+      locationId: "loc_other",
+      involvedEntityIds: [],
+      content: "Alice woke up.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_target",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice arrived at tavern.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_succeeding",
+      ownerId: "alice",
+      timestamp: "2024-01-10T12:00:00.000Z",
+      locationId: "loc_other",
+      involvedEntityIds: [],
+      content: "Alice ordered ale.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    // Without neighbors: only returns mem_target
+    const withoutNeighbors = repo.retrieve("alice", "loc1", [], undefined, new Date("2024-01-10T14:00:00.000Z"), 1, {
+      includeAssociativeNeighbors: false,
+    });
+    expect(withoutNeighbors).toHaveLength(1);
+    expect(withoutNeighbors[0].id).toBe("mem_target");
+
+    // With neighbors: returns preceding, target, and succeeding sorted chronologically
+    const withNeighbors = repo.retrieve("alice", "loc1", [], undefined, new Date("2024-01-10T14:00:00.000Z"), 1, {
+      includeAssociativeNeighbors: true,
+    });
+    expect(withNeighbors).toHaveLength(3);
+    expect(withNeighbors[0].id).toBe("mem_preceding");
+    expect(withNeighbors[1].id).toBe("mem_target");
+    expect(withNeighbors[2].id).toBe("mem_succeeding");
+  });
 });
--- a/web/docs/src/content/docs/architecture/memory-tier2.md
+++ b/web/docs/src/content/docs/architecture/memory-tier2.md
@@ -0,0 +1,115 @@
+---
+title: Tier 2 Memory (Ledger)
+description: Long-term episodic memory storage and retrieval
+---
+
+Tier 2 memory lives in between the memory buffer and tier 3 dossiers and arguably takes up the largest share of the context pie.
+
+Tier 2 memory (or long-term memory) stores historical events that happened to the entity in the past. It acts as an episodic ledger.
+
+```ts
+interface LedgerEntry {
+  id: string;
+  ownerId: string; // whose subjective memory this belongs to
+  timestamp: string; // ISO, tied to WorldClock when the intent causing the event happened.
+  locationId: string | null; // where it happened
+  involvedEntityIds: string[]; // who else this event concerns
+
+  content: string; // third-person narrative summary — recallable
+  quotes: string[]; // verbatim lines, only for high-salience dialogue
+  importance: number; // 1–10, salience assigned at handoff
+  embedding: number[]; // for semantic search (storage representation TBD at build time)
+}
+```
+
+### Storage Model
+
+Tier 2 memory is stored in relational tables to allow efficient deterministic filtering. Embeddings are stored as raw BLOBs (containing a serialized `Float32Array`). 
+
+To avoid the build and installation friction associated with native C-extensions like `sqlite-vec` (e.g. node-gyp issues across platforms), index optimization relies on standard SQLite secondary indices. These indices allow database queries to execute in microseconds, even with hundreds of thousands of memories:
+
+```sql
+CREATE TABLE IF NOT EXISTS ledger_entries (
+  id TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL,
+  timestamp TEXT NOT NULL,
+  location_id TEXT,
+  content TEXT NOT NULL,
+  quotes_json TEXT,
+  importance INTEGER NOT NULL,
+  embedding BLOB,
+  FOREIGN KEY (owner_id) REFERENCES objects(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS ledger_involved_entities (
+  entry_id TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  PRIMARY KEY (entry_id, entity_id),
+  FOREIGN KEY (entry_id) REFERENCES ledger_entries(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_ledger_owner ON ledger_entries(owner_id);
+CREATE INDEX IF NOT EXISTS idx_ledger_location ON ledger_entries(location_id);
+CREATE INDEX IF NOT EXISTS idx_ledger_importance ON ledger_entries(importance);
+CREATE INDEX IF NOT EXISTS idx_ledger_involved_entity ON ledger_involved_entities(entity_id);
+```
+
+### Handoff (Deferred)
+
+The process of moving memories from the Tier 1 working buffer into Tier 2 is called **Handoff**. 
+During handoff, an LLM chunk-summarizes raw buffer events, extracts salient quotes, and assigns an `importance` score (1-10). Routine actions score low, while life-altering events score high.
+
+Because this summarization requires an LLM call, it utilizes the standard `LLMProviderInstance` inference provider routing architecture just like all other callers in the system. This allows the simulation to route handoff processing to a specific model.
+
+*Note: The automated handoff pipeline is currently deferred for future implementation.*
+
+### Retrieval Architecture
+
+Retrieval happens in phases to manage context window limits without running expensive vector searches across an entity's entire lifetime of memories.
+
+#### Phase 1: Deterministic Heuristic Filtering
+
+This is the primary database-level retrieval mechanism. We use fast SQL queries to filter down to a relevant candidate pool based on immediate context:
+
+1. **Spatial Cues**: Fetch recent memories where `location_id` equals the entity's current location.
+2. **Social Cues**: Fetch recent memories involving the `involvedEntityIds` currently in the entity's perception radius.
+3. **High Salience**: Always fetch memories with `importance >= 8` regardless of spatial or social context.
+
+#### Phase 2: Semantic & Episodic Ranking
+
+This phase runs in application memory using the candidates returned from Phase 1:
+
+1. **Semantic Match**: Compute cosine similarity dynamically in JS/TS memory over the candidate pool (limit 100). Since Phase 1 narrows the pool down significantly, vector comparisons are highly performant in JS, eliminating the need for native vector database extensions.
+2. **Scoring Combination**: Combine recency, importance, and semantic match:
+   $$\text{Score} = (\text{recencyWeight} \times \text{recency}) + (\text{importanceWeight} \times \text{importanceNorm}) + (\text{relevanceWeight} \times \text{relevance})$$
+   Where `recency` uses an exponential decay based on elapsed hours ($\text{decayRate}^{\text{hoursElapsed}}$).
+3. **Associative Chain**: When a memory is selected, automatically pull in its immediate chronological neighbors (preceding and succeeding ledger entries) to preserve episodic continuity (mirroring how remembering one event triggers the memory of what happened right after).
+
+### Retrieval Triggers & Active Focus
+
+In crowded locations (e.g. a tavern with 15 other characters), retrieving memories for all co-located entities simultaneously would cause **context explosion**. To prevent this, Omnia utilizes an **Active Focus** trigger strategy:
+
+- **Active Focus Scanning**: The prompt builder scans the last 10 entries of the entity's recent working memory (Tier 1 Buffer). Any character that the actor has recently spoken to, thought about, or was targeted by is placed in the "Active Focus" set.
+- **Dynamic Thresholding**: 
+  - If the number of co-located entities is small ($\le 3$), long-term memory is retrieved for all of them.
+  - If the location is crowded ($> 3$ entities), the system **strictly** limits long-term retrieval to the top 3 characters in "Active Focus".
+- This creates a natural attention loop. When a new character interacts with the actor, they immediately enter "Active Focus" in the buffer, triggering the retrieval of their long-term history on the subsequent turn.
+
+### Integration into Prompts
+
+Recalled entries are formatted into the prompt using chronological relative time grouping. System-level metrics like salience/importance scores are omitted to preserve immersion, and system UUIDs are mapped to subjective aliases.
+
+To frame the prompt naturally:
+1. Tier 1 working buffer entries are presented under the header `=== RECENT EVENTS ===`, referring strictly to events happening in the present narrative context.
+2. Tier 2 recalled entries are presented under the header `=== YOUR MEMORIES ===`, framing them simply as the entity's memories.
+
+```text
+=== RECENT EVENTS ===
+Moments ago
+  - you spoke to Strider: "Hello there"
+
+=== YOUR MEMORIES ===
+A couple days ago
+  - You met a hooded figure named Strider at The Prancing Pony.
+    Quote: "I can avoid being seen, if I wish, but to disappear entirely, that is a rare gift."
+```
Author	SHA1	Message	Date
Aditya Gupta	597d4f1711	major(llm): Support Embedding Providers	2026-07-11 14:31:18 +05:30
Aditya Gupta	a5fa43e2e6	feat(memory): Implemented tier two memory retrieval using cognition model	2026-07-11 13:57:27 +05:30