Docs/Journal memory

Example

Journal memory

Import dated journal entries, preserve source metadata, retrieve themes across entries, and review private extracted memory.

Estimated time: 12 minutes

Level: Intermediate

Prerequisites:Installation·Quick Start·Ingesting & Extracting Memory

Overview

This example uses the session-oriented MemoGrafter ingestion API to attach distinct date tags to each entry. A MemoGrafterAgent then performs explicit cross-session tagged recall over the authorized journal collection.

What this demonstrates

Raw-text ingestion without generating assistant responses.

Per-entry date, journal, and user tags.

Source metadata for provenance.

Theme recall across several entry sessions.

The distinction between topic summaries and exact atomic memories.

Architecture

Dated entries

Source sessions

Topics and memories

Authorized tagged recall

Memory design

One explicit ingestion session per journal entry.

Tags such as journal, user:alice, and date:2026-07-21.

Source metadata pointing to the application’s journal entry ID.

Topic summaries for broad entry themes and memory nodes for exact activities, feelings, or observations.

Project structure

files

src/
  memory-config.ts
  ingest-entry.ts
  recall-themes.ts
  journal-example.ts

Step 1: Ingest dated entries

src/ingest-entry.ts

await memo.ingestText(
  "A morning walk and an hour of focused writing made me feel energized.",
  "journal-entry-2026-07-21",
  {
    label: "Journal entry: 2026-07-21",
    source: "journal:entry-184",
    tags: ["journal", "user:alice", "date:2026-07-21"],
  },
);

await memo.ingestText(
  "Back-to-back late meetings left me drained, but cooking helped me reset.",
  "journal-entry-2026-07-22",
  {
    label: "Journal entry: 2026-07-22",
    source: "journal:entry-185",
    tags: ["journal", "user:alice", "date:2026-07-22"],
  },
);

Step 2: Recall themes across entries

scope: tagged intentionally searches matching active memories across sessions. The application must authorize the journal owner before making this query.

src/recall-themes.ts

const themes = await reader.recall(
  "Which activities consistently increase Alice's energy?",
  {
    tags: ["journal", "user:alice"],
    tagMode: "all",
    scope: "tagged",
    limit: 10,
    minSimilarity: 0.4,
  },
);

console.log(themes.facts);

Complete example

src/journal-example.ts

import "dotenv/config";

import {
  MemoGrafter,
  MemoGrafterAgent,
  OpenAIEmbedAdapter,
  OpenAILLMAdapter,
} from "memo-grafter";

const config = {
  db: { connectionString: process.env.DATABASE_URL! },
  llm: new OpenAILLMAdapter("gpt-4o"),
  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
};

const memo = new MemoGrafter(config);
const reader = new MemoGrafterAgent(config);
await memo.initialize();
await reader.initialize();

try {
  await memo.ingestText(
    "A morning walk and focused writing made me feel energized.",
    "journal-entry-2026-07-21",
    {
      source: "journal:entry-184",
      tags: ["journal", "user:alice", "date:2026-07-21"],
    },
  );

  await memo.ingestText(
    "Late meetings left me drained, but cooking helped me reset.",
    "journal-entry-2026-07-22",
    {
      source: "journal:entry-185",
      tags: ["journal", "user:alice", "date:2026-07-22"],
    },
  );

  const themes = await reader.recall("What increases Alice's energy?", {
    tags: ["journal", "user:alice"],
    scope: "tagged",
    tagMode: "all",
    minSimilarity: 0.4,
  });

  console.log(themes.facts);
} finally {
  await Promise.all([memo.close(), reader.close()]);
}

Expected behavior

The first entry can yield memories about walking, writing, and increased energy.

The second can yield memories about meeting fatigue and cooking as recovery.

Cross-session tagged recall can surface walking, focused writing, or cooking as relevant patterns.

Exact extracted wording varies with the configured LLM.

What gets stored

Each entry’s raw text in its explicit entry session.

One or more topic segments when an entry changes subject.

Topic summaries carrying source and date tags.

Atomic memories representing activities, observations, questions, or insights.

No public conversational history because the entries use text ingestion.

Inspect it in Studio

Open each journal entry session separately.

Inspect topic boundaries in multi-topic entries.

Confirm source values and normalized date tags.

Use Prompt Preview with the same theme query and tagged scope.

Review private lifecycle actions carefully before forgetting memory.

Privacy considerations

Authorize the journal owner before using cross-session tagged recall.

Treat tags as filters, never access controls.

Avoid logging raw entries or prompts by default.

Define policies for graph rows, application records, backups, exports, and provider retention.

Use exact reviewed memory IDs for user-directed forgetting.

Common mistakes

Using one rolling summary and losing source-level provenance.

Applying date tags to an existing agent with setSessionTags(), which replaces tags across that whole session.

Assuming topic summaries and atomic memories contain identical information.

Using scope: tagged before tenant and user authorization.

Promising exact extracted themes without evaluation.

Extensions

Add mood, project, or activity tags during entry ingestion.

Build a reviewed theme dashboard from graph snapshots.

Compare weekly themes while keeping source entries traceable.

Add a user-directed privacy workflow for exact extracted memories.