Tags & memory scope

Organize memory with normalized tags and choose deliberately between session-local and cross-session retrieval.

Estimated time: 8 minutes

Level: Intermediate

Overview

A session is MemoGrafter’s normal memory boundary. Tags are optional metadata for filtering or intentionally searching related memory across sessions; they do not replace sessions or application authorization.

Scope model

Application identity

Session boundary

Optional tags

Authorized recall

Step 1: Set session tags

Tags are trimmed, lowercased, deduplicated, and sorted. Setting session tags waits for pending ingestion, updates existing session topics and memories, and applies the tags to future ingestion.

tags.ts

await agent.setSessionTags([
  "tenant:acme",
  "project:memo-grafter",
  "planning",
]);

console.log(agent.getSessionTags());

Step 2: Recall within the session

session-tags.ts

const result = await agent.recall("deployment decisions", {
  tags: ["project:memo-grafter", "planning"],
  tagMode: "all",
  scope: "session-and-tags",
});

Step 3: Search tagged memory across sessions

scope: tagged is an explicit cross-session operation. Authorize the caller before issuing it.

cross-session.ts

const result = await agent.recall("deployment decisions", {
  tags: ["tenant:acme", "project:memo-grafter"],
  tagMode: "all",
  scope: "tagged",
  minSimilarity: 0.4,
});

Full example

project-scope.ts

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

const llm = new OpenAILLMAdapter("gpt-4o");
const embedder = new OpenAIEmbedAdapter("text-embedding-3-small");

const agent = new MemoGrafterAgent({
  db: { connectionString: process.env.DATABASE_URL! },
  llm,
  embedder,
});

await agent.initialize();

try {
  await agent.setSessionTags(["tenant:acme", "project:apollo"]);
  await agent.remember("Apollo production deploys to eu-west-1.");

  const projectMemory = await agent.recall("production region", {
    tags: ["tenant:acme", "project:apollo"],
    tagMode: "all",
    scope: "session-and-tags",
  });
  console.log(projectMemory.facts);
} finally {
  await agent.close();
}

Scope reference

session: search the current session without tag filtering.

session-and-tags: search the current session and require the selected tag rule.

tagged: search active memories across sessions that match the selected tags.

all: require every requested tag.

any: accept at least one requested tag.

Security boundary

Tags filter memory but are not an authorization boundary. Resolve and authorize the tenant, user, project, and allowed sessions in application code before calling MemoGrafter.

Common mistakes

Using a tag as a substitute for a session ID.

Running scope: tagged without tenant authorization.

Expecting differently cased tags to remain distinct after normalization.

Using any when every project or tenant tag is required.

Forgetting that repeated smoke tests can leave older tagged sessions in the database.