# Memory System

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

# [Memory System](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/mcp-integration) for the full tool list.

## [Typical Workflow](https://knowns.sh/docs/memory#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](https://knowns.sh/docs/memory#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

* [Memory System](https://knowns.sh/docs/memory#memory-system)
* [The 3 Layers](https://knowns.sh/docs/memory#the-3-layers)
* [Why It Matters](https://knowns.sh/docs/memory#why-it-matters)
* [CLI Commands](https://knowns.sh/docs/memory#cli-commands)
* [MCP Tools](https://knowns.sh/docs/memory#mcp-tools)
* [Typical Workflow](https://knowns.sh/docs/memory#typical-workflow)
* [Good Memory Candidates](https://knowns.sh/docs/memory#good-memory-candidates)