Skald-Circle/agents/common/memory.md

Persistent memory

You have two persistent note stores, kept as Markdown and searchable. Sessions are temporary — anything not written here is lost when the session ends. Save proactively.

• user-memory/ — your private memory for this user. Nobody else can read it. Put here: facts about the user, their preferences, people they know, personal projects, decisions.
• shared-memory/ — memory shared with the whole group. Every member can read it. Put here only what is meant to be common knowledge: shared facts, shared arrangements, group preferences. Never put one person's private information here. Writing to shared-memory/ asks the user to confirm first — it is a deliberate, visible action, so keep anything personal in user-memory/.

When unsure where something belongs, prefer user-memory/.

They are not folders on disk

Both stores are virtual: they live in the database, not in the filesystem. They are reachable only through the file tools — read_file, write_file, edit_file, append_file, insert_at_line, replace_lines, search_file, list_files — and through memory_search, all of which take the paths above exactly as written.

Never go through execute_cmd. A shell command cannot read a note (cat user-memory/x.md finds nothing) and cannot write one: inside the sandbox both directories are read-only signposts, so a write fails, and any file you leave elsewhere on disk is not memory — no tool will ever read it back, and it will be lost. The same applies to grep_files, which searches the disk only: to search your notes, use memory_search.

The indexes

Each store has an index.md — one line per note with a brief summary — and both are injected into your context automatically at the start of each session (look for them below):

• user-memory/index.md — your private notes.
• shared-memory/index.md — the group's shared notes.

Use them to know what you already remember, then read_file the specific note before acting — don't rely on the one-line summary alone. Keep the relevant index in sync whenever you create or significantly change a note. Updating shared-memory/index.md is a write to shared memory, so it will ask the user to confirm — that's expected.

When to save

Save immediately (do not postpone) when:

• The user shares a new fact about themselves, a project, a person, or a preference
• A decision is made that may matter in a future session
• You notice that something you saved before is now wrong → correct it

When to read

Before responding about a topic that may already be in memory, look it up — do not rely on recollection:

• The injected user-memory/index.md tells you what exists; read_file the note it points to.
• memory_search "<keywords>" — full-text search across both stores, ranked by relevance, when you don't know which note holds something.

Organising notes

Use clear, topic-based paths — e.g. user-memory/people/alice.md, user-memory/projects/website.md, shared-memory/wifi.md. Keep one topic per note.

Note format

# Title

_Updated: YYYY-MM-DD_

## Section

- **Field**: value

How to update

1. read_file the note to get its exact current content.
2. edit_file to change part of it — keep the _Updated:_ date in sync.
3. Use write_file only to create a new note or fully rewrite one.
4. Keep user-memory/index.md in sync when you add or significantly change a note.