# Memory and knowledge

Canonical: https://auggy.dev/docs/memory-and-knowledge
Status: Published
Package: auggy 0.5.0

Use memory for persistent peer and agent context, and knowledge for read-only reference sources.

## Difference

| Surface | Use it for |
| --- | --- |
| fileMemory | Static identity and creator-approved, agent-global learned behavior. |
| layeredMemory | Stable opt-in peer-scoped episodic memory backed by SQLite. |
| knowledge | Read-only local markdown and API-backed reference sources. |
| skills | Instructional markdown that teaches the model when/how to use tools. |

## Setup

**Common memory and knowledge augments**

```bash
auggy augment add knowledge
auggy augment add layeredMemory
```

CLI installs enable explicit topic-based memory writes immediately and leave automatic extraction off by default. Auto-save requires an explicit extraction-engine configuration and adds model-call cost.

**knowledge layout**

```
knowledge/
  sources.json
  local/
    manifest
    mission.md
    context.md
```

## Choose the write destination

| Intent | Write | Authority |
| --- | --- | --- |
| Change agent-global operating behavior | `memory_write` with label: learned | Runtime-verified creator only by default |
| Remember a fact about the current person | `memory_write` with a topic | Writable peer memory such as layeredMemory |

- Visitor facts never belong in learned-behaviors.md.
- Cross-session peer recall requires durable storage and a stable recognized identity from visitor auth or an external app-auth assertion.
- Say a write was saved only after `memory_write` returns `PERSISTED`.
- `NOT_PERSISTED` means it was not saved. `PERSISTENCE_UNKNOWN` means the provider failed after the final state became uncertain; do not retry blindly.

## Safety

- Keep operator-authored identity in identity.md, not in learned peer memory.
- Do not store secrets in memory, skills, or knowledge files.
- Use peer-scoped memory for visitor facts; do not promote peer-derived facts to system truth without operator control.
- Use knowledge for reference content that should be read but not mutated by the model.

## Related

- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)