Memory System

Persistent project memory for AI agents with working, project, and global layers

Memory System

Knowns includes a 3-layer memory system so agents can retain patterns, decisions, and conventions across sessions instead of relearning them every time.

The 3 Layers

Layer Scope Best for
Working Current session only Temporary notes, active investigation context
Project Current repository Team conventions, architecture decisions, reusable patterns
Global Across projects Personal defaults and broadly reusable practices

Why It Matters

  • Agents can load project memory at session start
  • Reusable learnings stop disappearing between sessions
  • Important patterns can be promoted instead of copied into every prompt
  • Search and graph views can connect memories to tasks and docs

CLI Commands

Persistent memory is managed with the knowns memory command group:

# List memory entries
knowns memory list --plain

# Filter by layer or category
knowns memory list --layer project --category pattern --plain

# View a memory entry
knowns memory view <id> --plain

# Add a new memory entry
knowns memory add \
  --title "Auth token rotation pattern" \
  --category pattern \
  --tags auth,security \
  --content "Rotate access tokens every 15 minutes"

# Promote reusable knowledge
knowns memory promote <id>
knowns memory demote <id>

MCP Tools

MCP has full memory coverage for both persistent and session-scoped memory (v0.20 consolidated format):

Persistent memory:

memory({ action: "add", title: "Auth pattern", category: "pattern", layer: "project", content: "..." })
memory({ action: "list", layer: "project" })
memory({ action: "get", id: "abc123" })
memory({ action: "update", id: "abc123", content: "..." })
memory({ action: "promote", id: "abc123" })  // project → global
memory({ action: "demote", id: "abc123" })   // global → project

Search memory:

search({ action: "search", query: "auth pattern", type: "memory" })

See MCP Integration for the full tool list.

Typical Workflow

Research something once
→ save the distilled lesson to project memory
→ load it automatically in later sessions
→ promote it to global if it applies everywhere

Good Memory Candidates

  • Architecture decisions that should not be re-debated every session
  • Team conventions that are easy for agents to miss
  • Reusable debugging lessons
  • Patterns extracted from completed tasks

On this page