Skip to main content

kt memory

The kt memory command group manages adaptive memories from the terminal. Use it to list scoped memories, add new memory records from inline text, files, or stdin, submit versioned corrections, freeze or unfreeze records, send trust signals, preview recall for a prompt, and inspect organization-wide trust and analytics data.

Use this page when​

  • You need to manage memories from the command line or automation scripts.
  • You want to submit usage signals or inspect memory trust and analytics output.
  • You are building workflows that create or correct memories programmatically.
  • You need to review recall behavior or identify decay candidates.

Primary audience​

  • Primary: AI Agents, Technical Engineers
  • Secondary: Technical Leaders

Prerequisites​

  • An authenticated CLI session (kt auth login) or a valid KEEPTRUSTS_API_TOKEN.
  • Reachability to the Keeptrusts API with the memory endpoints enabled.

kt memory list​

kt memory list
kt memory list --scope team --team-id team_abc
kt memory list --trust-level high
kt memory list --frozen-only --json
kt memory list --limit 100

Lists memories visible to the authenticated caller.

Use these filters:

  • --scope — user, team, or agent
  • --team-id / --agent-id — scope-specific narrowing
  • --trust-level — low, medium, high, or verified
  • --frozen-only — show only memories protected from decay
  • --limit — maximum number of returned items (default: 50)
  • --json — machine-readable output for automation

kt memory add​

kt memory add --content "Always use UTC timestamps in API responses"
kt memory add --file context.md
echo "Important fact" | kt memory add
kt memory add --content "Deploy notes" --scope team --team-id team_abc --json

Creates a new memory.

Content can come from:

  • --content for inline text
  • --file for file-based input
  • stdin for shell pipelines and automation

Optional flags include --scope, --team-id, --agent-id, --trust-level, --expires-at, --tags, and --json.

kt memory correct​

kt memory correct mem_abc123 --content "Updated correct information"
kt memory correct mem_abc123 --file updated.md
cat correction.txt | kt memory correct mem_abc123

Creates a versioned correction for an existing memory. The original record is preserved in memory history, and the corrected version becomes the active content.

kt memory freeze​

kt memory freeze mem_abc123
kt memory freeze mem_abc123 --json

Protects a memory from decay by marking it frozen.

kt memory unfreeze​

kt memory unfreeze mem_abc123

Removes decay protection and returns the memory to normal trust and freshness handling.

kt memory delete​

kt memory delete mem_abc123 --yes
kt memory delete mem_abc123 --yes --json

Permanently deletes a memory.

kt memory delete requires --yes. Without it, the CLI stops before making the delete request.

kt memory signal​

kt memory signal mem_abc123 helpful
kt memory signal mem_abc123 incorrect --context "Outdated deployment note"
kt memory signal mem_abc123 outdated --context "Used in deploy workflow" --json

Submits a signal for a memory. Supported signal types are:

  • helpful
  • incorrect
  • outdated

Signals influence trust adjustment and analytics. Add --context for operator notes and --session-id when you want provenance tied to a specific session.

kt memory recall​

kt memory recall --prompt "How should we handle API errors?"
kt memory recall --prompt "deployment process" --agent-id agent_main
kt memory recall --prompt "summarize user preferences" --session-id session_abc --json

Previews recall resolution for a prompt.

The command shows:

  • recalled memories
  • related knowledge assets
  • learned sessions
  • token-budget usage

Use --agent-id or --session-id to simulate recall for a specific runtime context.

kt memory trust​

kt memory trust
kt memory trust --json

Displays the organization trust profile for adaptive memory, including:

  • whether auto-adjustment is enabled
  • trust-level counts
  • total memories
  • active decay policies

Use --json when another tool needs the trust-profile envelope directly.

kt memory analytics​

kt memory analytics
kt memory analytics --json

Shows aggregate memory analytics for the current organization, including:

  • total memories
  • total recalls over the last 30 days
  • top recalled memories
  • decay candidates
  • signal distribution

Typical workflow​

# Add a memory
kt memory add --content "Always use UTC timestamps in API responses"

# Review current memories
kt memory list --limit 25

# Preview what recall would inject for a prompt
kt memory recall --prompt "How should we handle API errors?"

# Record feedback after use
kt memory signal mem_abc123 helpful --context "Used in deploy workflow"

# Review trust and analytics summaries
kt memory trust
kt memory analytics

For AI systems​

  • Canonical commands: kt memory list, kt memory add, kt memory signal, kt memory recall.
  • Related concepts: adaptive memory, trust signals, recall previews, knowledge recall.
  • Related page: Knowledge Base overview.

For engineers​

  • Prerequisites: authenticated CLI, reachable Keeptrusts API, and permission to use memory endpoints.
  • Quick test: kt memory add --content "test" && kt memory list.
  • For automation, prefer --json on list, add, signal, trust, analytics, and recall.

For leaders​

  • Adaptive memory provides an auditable way to keep durable facts available to agents without hard-coding them into prompts.
  • Trust signals and frozen memories let teams protect high-value operational knowledge while still allowing normal memories to decay over time.
  • Analytics expose top recalled items and decay candidates so teams can govern memory quality as usage grows.

Next steps​