Skip to main content

​
Overview

Generate a stable topic_key that allows evolving topics (like architecture decisions) to update a single observation over time instead of creating duplicates. The tool analyzes the type, title, and content to suggest a normalized, cross-session key.
This tool is part of the agent profile and uses deferred loading to optimize performance.

​
Parameters

​
type
string
Observation type/category (e.g., architecture, decision, bugfix, pattern)Recognized types that map to topic families:
  • architecture, design, adr, refactor → architecture/*
  • bug, bugfix, fix, incident, hotfix → bug/*
  • decision → decision/*
  • pattern, convention, guideline → pattern/*
  • config, setup, infra, infrastructure, ci → config/*
  • discovery, investigation, root_cause → discovery/*
  • learning, learn → learning/*
  • session_summary → session/*
​
title
string
Observation title (preferred input for stable keys)The title is the primary source for generating the topic segment. It’s normalized by:
  • Converting to lowercase
  • Removing special characters
  • Replacing spaces with hyphens
  • Stripping private tags (anything in [brackets])
​
content
string
Observation content (used as fallback if title is empty)If no title is provided, the first 8 words of the content are used to generate the topic segment.

​
Response

​
topic_key
string
Suggested topic key in the format family/segment
The suggested key follows the pattern: {family}/{normalized-segment} Examples:
  • architecture/jwt-auth-model
  • bug/fts5-query-sanitization
  • pattern/structured-memory-format
  • config/sqlite-fts5-setup

​
Topic Key Generation Logic

​
1. Infer Topic Family

The algorithm first determines the topic family based on:
  1. The type parameter (if it matches a known category)
  2. Keywords in the title and content (if type doesn’t match)
  3. Defaults to "topic" if no match

​
2. Normalize Segment

From the title (or content fallback):
  1. Strip private tags in [brackets]
  2. Convert to lowercase
  3. Replace spaces and special chars with hyphens
  4. Remove redundant family prefix (e.g., “bug-” from segment if family is “bug”)
  5. Default to "general" if empty

​
3. Combine

Returns {family}/{segment}

​
Usage Examples

​
Architecture Decision

{
  "type": "architecture",
  "title": "JWT authentication model",
  "content": "Replaced session-based auth with JWT tokens..."
}
Response: 
Suggested topic_key: architecture/jwt-authentication-model

​
Bug Fix

{
  "type": "bugfix",
  "title": "FTS5 query sanitization"
}
Response: 
Suggested topic_key: bug/fts5-query-sanitization

​
Pattern Without Type

{
  "title": "Structured memory format for What/Why/Where/Learned"
}
Response: 
Suggested topic_key: pattern/structured-memory-format-for-what-why-where-learned

​
Fallback to Content

{
  "type": "config",
  "content": "Set up SQLite with FTS5 extension for full-text search on observations table"
}
Response: 
Suggested topic_key: config/set-up-sqlite-with-fts5-extension-for

​
When to Use

  • Before mem_save: When you want evolving topics to update a single observation
  • Architectural decisions: Track how decisions evolve over time
  • Ongoing bugs: Update the same memory as investigation progresses
  • Living documentation: Keep a single observation for patterns or conventions

​
Workflow

// 1. Get suggestion
const suggestion = await mem_suggest_topic_key({
  type: "architecture",
  title: "Database schema design"
});
// Returns: "architecture/database-schema-design"

// 2. Use in mem_save
await mem_save({
  title: "Database schema design",
  type: "architecture",
  content: "...",
  topic_key: "architecture/database-schema-design"
});

// 3. Later updates with same topic_key will revise the observation
await mem_save({
  title: "Database schema design [updated]",
  type: "architecture",
  content: "[Updated approach]...",
  topic_key: "architecture/database-schema-design"
});
// This updates the existing observation instead of creating a duplicate
Topic keys must be consistent across saves to enable upserts. Use this tool to ensure stability.
  • mem_save - Save or upsert observations with topic keys
  • mem_update - Update observations by ID

Build docs developers (and LLMs) love

Get started for freeTalk to us