# Add an augment

Canonical: https://auggy.dev/docs/add-augment
Status: Published
Package: auggy 0.5.0

Install layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.

## Add memory without runtime code

This guide adds the stable layeredMemory augment to the agent from the previous step. It gives the agent peer-scoped SQLite memory, model-callable memory tools, recent-memory context, and bundled guidance without asking you to write TypeScript.

**What changes**

```
Conversation
  -> memory_write({ topic, content })
  -> data/memory.db
  -> recent memory on a later turn for the same peer
```

## Install layeredMemory

**Run from the agent project**

```bash
cd my-agent
auggy augment add layeredMemory
```

The command enables the augment in agent.yaml, writes project-owned configuration, and copies its bundled skill. layeredMemory has no additional npm package or environment-variable requirement.

## Inspect the installed files

**Relevant project changes**

```
my-agent/
  agent.yaml                         # lists layeredMemory in boot order
  augments/
    README.md
    layeredMemory/
      augment.yaml                   # project-owned config
  skills/
    layeredMemory/
      SKILL.md                       # installed guidance snapshot
  data/
    memory.db                        # created when the runtime boots
```

**augments/layeredMemory/augment.yaml**

```yaml
type: layeredMemory
config:
  backend: sqlite
  dbPath: ./data/memory.db
  namespace: my-agent
  retentionDays: 90
  autoSave:
    enabled: false
```

> **Note: Config here, implementation in the package**
>
> Built-in runtime source remains inspectable under `node_modules`/auggy/src. The local augment folder contains configuration so package updates can deliver runtime and security fixes without replacing project-owned settings.

## Validate and boot

**Restart with the new augment**

```bash
auggy doctor
auggy run
```

doctor checks the project before startup. The runtime initializes the SQLite store on boot, so data/memory.db appears after run starts rather than during augment add.

## Verify memory in Console

1. Open `/console/chat` and keep the caller set to Creator. Creator has the stable peer ID creator, which makes this local check repeatable.
2. Send: Remember that I prefer concise replies.
3. Expand the `memory_write` tool call. Confirm it used a topic such as preferences and returned `PERSISTED`.
4. Start a new chat as Creator and ask: What response style do I prefer? Recent peer memory should supply the preference; the agent can use `memory_search` for a targeted lookup.

| Result | Meaning |
| --- | --- |
| `PERSISTED` | The selected provider confirmed the write. |
| `NOT_PERSISTED` | Nothing was saved; inspect the tool result and runtime logs. |
| `PERSISTENCE_UNKNOWN` | The provider failed after the final state became uncertain; inspect before retrying. |

> **Warning: A repeat visitor needs stable identity**
>
> Cross-session visitor recall requires visitorAuth or an application-auth assertion that resolves the same recognized peer. Anonymous identities are session-scoped by default.

## Know what the skill adds

| Layer | Responsibility |
| --- | --- |
| Tool schema and description | Expose `memory_search`, `memory_write`, `memory_list`, and `memory_forget` and explain their immediate purpose. |
| Bundled skill | Teach what is worth saving, peer scoping, privacy boundaries, retrieval strategy, and persistence-result handling. |
| Runtime | Derive the current peer, enforce authorization, isolate stored entries, and inject recent memory. |

**Refresh the bundled skill later**

```bash
auggy skill add layeredMemory
```

Refresh overwrites the installed layeredMemory skill snapshot. Keep project-specific teaching in a separate user-authored skill.

## Go deeper or build your own

| Next | Use it for |
| --- | --- |
| [Augments](https://auggy.dev/docs/augments/markdown) | Understand composition, ownership, and the built-in catalog. |
| [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown) | Choose memory destinations and identity requirements. |
| [Skills](https://auggy.dev/docs/add-skills/markdown) | Learn when model guidance belongs in a skill. |
| [Console](https://auggy.dev/docs/console/markdown) | Inspect caller identity, capabilities, and tool results. |
| [Build an augment](https://auggy.dev/docs/build-augment/markdown) | Author a project-specific typed capability in TypeScript. |

## Related

- [Augments](https://auggy.dev/docs/augments/markdown)
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)