neuroverse

Instructions

Implementation Reference

• npm/src/index.ts:152-197 (handler)

  The MCP tool registration and handler function for "neuroverse_store" in `npm/src/index.ts`. It invokes `storeMemory` from `core/memory.ts`.

  server.registerTool(
    "neuroverse_store",
    {
      title: "Store Memory",
      description: `Store a memory record in NeuroVerse's tiered memory system.
  
  Tiers:
    - short_term: In-process, capped at 50 per user. Lost on restart.
    - episodic: Persisted to JSON file. Recent actions.
    - semantic: Persisted to JSON file. Long-term facts.
  
  Only episodic/semantic memories with importance_score ≥ 0.4 are persisted.
  
  Args:
    - user_id (string): Agent / user identifier
    - intent (string): Canonical intent name
    - tier (string): short_term | episodic | semantic
    - language (string): Language code (default: "en")
    - data (object): Structured payload
    - importance_score (number): 0.0–1.0
  
  Returns:
    JSON of the stored MemoryRecord`,
      inputSchema: StoreMemorySchema,
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
    },
    async (params) => {
      const record = await storeMemory({
        userId: params.user_id,
        intent: params.intent,
        tier: params.tier as MemoryTier,
        language: params.language,
        data: params.data as Record<string, unknown>,
        importanceScore: params.importance_score,
      });
  
      return {
        content: [{ type: "text" as const, text: JSON.stringify(record, null, 2) }],
      };
    }
  );

• npm/src/core/memory.ts:89-134 (helper)

  The actual implementation of `storeMemory`, which handles tiered memory storage (short-term in-memory vs persistent storage).

  /**
   * Store a memory record in the appropriate tier.
   */
  export async function storeMemory(record: Partial<MemoryRecord> & { userId: string; intent: string }): Promise<MemoryRecord> {
    const now = new Date().toISOString();
    
    let vector: number[] | undefined;
    if (record.tier && record.tier !== "short_term" && record.importanceScore !== undefined && record.importanceScore >= IMPORTANCE_THRESHOLD) {
       const textToEmbed = JSON.stringify(record.data);
       if (textToEmbed && textToEmbed !== "{}") {
         vector = await generateEmbedding(textToEmbed);
       }
    }
  
    const full: MemoryRecord = {
      id: record.id ?? randomUUID(),
      userId: record.userId,
      tier: (record.tier ?? "short_term") as MemoryTier,
      intent: record.intent,
      language: record.language ?? "en",
      data: record.data ?? {},
      importanceScore: record.importanceScore ?? 0.5,
      vector,
      createdAt: record.createdAt ?? now,
      updatedAt: now,
    };
  
    if (full.tier === "short_term") {
      const existing = shortTerm.get(full.userId) ?? [];
      existing.push(full);
      // Cap
      if (existing.length > MAX_SHORT_TERM) {
        existing.shift();
      }
      shortTerm.set(full.userId, existing);
    } else {
      // Episodic / Semantic — persist only above threshold
      if (full.importanceScore >= IMPORTANCE_THRESHOLD) {
        const records = loadPersistent();
        records.push(full);
        savePersistent(records);
      }
    }
  
    return full;
  }

• npm/src/index.ts:130-150 (schema)

  The Zod schema used for input validation of the "neuroverse_store" tool.

  const StoreMemorySchema = z
    .object({
      user_id: z.string().min(1).describe("Agent / user identifier"),
      intent: z.string().min(1).describe("Canonical intent this memory relates to"),
      tier: z
        .enum(["short_term", "episodic", "semantic"])
        .default("short_term")
        .describe("Memory tier"),
      language: z.string().default("en").describe("Primary language code"),
      data: z
        .record(z.unknown())
        .default({})
        .describe("Structured memory payload"),
      importance_score: z
        .number()
        .min(0)
        .max(1)
        .default(0.5)
        .describe("Importance score — only above 0.4 are persisted for episodic/semantic"),
    })
    .strict();