# Memory API

Read, write, and delete agent and global memory files via HTTP.

Memory files are plain Markdown stored under `.veil/memory/`. They are injected into the agent's system prompt at session start.

---

## Agent Memory

### `GET /agents/:name/memory`

List all memory files for an agent.

```bash
curl http://localhost:5050/agents/assistant/memory
```

**Response:**
```json
{
  "agentName": "assistant",
  "files": [
    { "name": "MEMORY.md", "size": 1240, "modified": "2025-03-04T12:00:00.000Z" }
  ]
}
```

---

### `GET /agents/:name/memory/:file`

Read a specific memory file.

```bash
curl http://localhost:5050/agents/assistant/memory/MEMORY.md
```

**Response:**
```json
{
  "agentName": "assistant",
  "file": "MEMORY.md",
  "content": "## Notes\n\nProject uses port 5050."
}
```

**Errors:** `404 NOT_FOUND` if file does not exist.

---

### `PUT /agents/:name/memory/:file`

Write or replace a memory file. Creates the file if it does not exist.

```bash
curl -X PUT http://localhost:5050/agents/assistant/memory/MEMORY.md \
  -H "Content-Type: application/json" \
  -d '{"content": "## Project Notes\n\nThis project uses port 5050."}'
```

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `content` | string | ✓ | Full Markdown content to write |

**Response:**
```json
{
  "agentName": "assistant",
  "file": "MEMORY.md",
  "size": 47
}
```

**Errors:** `400 VALIDATION_ERROR` if `content` is not a string or filename is invalid.

---

### `DELETE /agents/:name/memory/:file`

Delete a memory file.

```bash
curl -X DELETE http://localhost:5050/agents/assistant/memory/MEMORY.md
```

**Response:**
```json
{ "agentName": "assistant", "file": "MEMORY.md", "status": "deleted" }
```

**Errors:** `404 NOT_FOUND` if file does not exist.

---

---

## Global Memory

Global memory files are shared across all agents. Stored at `.veil/memory/`.

### `GET /memory`

List all global memory files.

```bash
curl http://localhost:5050/memory
```

**Response:**
```json
{
  "files": [
    { "name": "MEMORY.md", "size": 512, "modified": "2025-03-04T12:00:00.000Z" }
  ]
}
```

---

### `GET /memory/:file`

Read a global memory file.

```bash
curl http://localhost:5050/memory/MEMORY.md
```

**Response:**
```json
{
  "file": "MEMORY.md",
  "content": "## Global Notes\n\nShared across all agents."
}
```

---

### `PUT /memory/:file`

Write or replace a global memory file.

```bash
curl -X PUT http://localhost:5050/memory/MEMORY.md \
  -H "Content-Type: application/json" \
  -d '{"content": "## Global Notes\n\nUpdated content."}'
```

**Response:**
```json
{
  "file": "MEMORY.md",
  "size": 35
}
```

---

### `DELETE /memory/:file`

Delete a global memory file.

```bash
curl -X DELETE http://localhost:5050/memory/MEMORY.md
```

**Response:**
```json
{ "file": "MEMORY.md", "status": "deleted" }
```

---

## File Name Rules

Memory file names must match the pattern `[a-z0-9A-Z_-]+.md`. Path traversal (`../`) is rejected with `400 VALIDATION_ERROR`.

---

## Notes

- Agent-scoped files: `.veil/memory/agents/<name>/<file>`
- Global files: `.veil/memory/<file>`
- Changes take effect on the **next session** — currently running sessions are not affected.
- To seed an agent's memory before first run, use this API to write a `MEMORY.md` file.

### HTTP `PUT` vs the `memory_write` tool

These two paths have **different write semantics by design** — pick the one that matches your use case:

| Surface | Empty-content rejection | Exact-entry dedup | Behavior |
|---------|-----------------------|-------------------|----------|
| `memory_write` tool (called by an agent) | ✓ returns `skipped_empty` | ✓ returns `skipped_duplicate` | Append-only with cleanup guards. Whitespace-only writes and back-to-back duplicates are silently dropped. |
| HTTP `PUT /memory/:file` and `PUT /agents/:name/memory/:file` | ✗ | ✗ | Literal overwrite via `fs.writeFileSync`. Whatever you send is what's on disk. |

**Why the asymmetry?** The tool is invoked by an LLM agent during a run — guards prevent garbage entries and noisy duplication. The HTTP endpoint is used by humans, dashboards, and seed scripts that legitimately need to set the file contents exactly. If you want guard semantics from a script, run the `memory_write` tool through `POST /agents/:name/chat` (or have an agent perform the write).