dguiducci
434e27d7c2
Nightly Build / build (push) Successful in 7m14s
Memory is kept as a maintained wiki, and a wiki nobody prunes rots. This adds
the scheduled maintenance pass, and generalises the machinery TIC had grown so
that a background agent is a trait impl rather than a loop of its own.
Two lint agents, not one. The private pass runs per user over `user-memory/`
and reports to them; the shared pass runs once over `shared-memory/`, where the
interesting defect is different — a note failing the table rule, i.e. private
business written where every member can read it. It names the note and the
category without repeating the content, since restating it spreads the very
thing being flagged. Both share `agents/common/memory-lint.md`.
Both are read-only, and that is enforced twice: the prompt says report-never-
repair, and `shared-memory/*` writes are already `@fs_write require`, so an
agent that tried to fix something would raise an approval card from an
unattended pass, which is auto-denied. Read-only is the only design that works
here, not merely the safe one.
One scheduler for cadences three orders of magnitude apart. TIC runs every few
minutes, a lint weekly — the case that tempts a second loop. It stays one
because the wake-up decides nothing: `base_tick` picks only how often to look,
and whether an agent runs for a user is `is_due` against persisted state.
Due-ness moves out of the run log into a new owner table, `system_agent_state`.
The two answer different questions: the run log skips idle ticks so it stays a
history rather than a heartbeat, while scheduling needs every attempt. Reading
due-ness off the log would re-run an idle agent on every tick and never bring a
weekly one due once its last productive run aged out. Persisting it is also
what makes a long interval survive a restart — an in-memory deadline is fine at
TIC's scale, but a weekly agent on a box rebooted every few days would have it
re-armed before it ever fired.
The shared store belongs to nobody, so `AgentScope::Instance` runs that pass as
the first unlocked admin. An ownerless run would write its trace into system.db,
which the runs endpoint shows to nobody by design, and its notify() would have
no recipient; attributing it to a user keeps the whole per-user surface working
unchanged.
Settings move to where the run log is. `ConfigSet` gains `owner`, so placement
is data on the set rather than a page that knows set names; the System agents
page grows one tab per agent holding its description, its settings (admin only)
and its runs — "why did this do nothing last night?" is half a schedule
question and half a log question. The form is shared with the Config page, and
writes still go through PUT /api/config/{key}.
Fixes an authorization gap found on the way: neither /api/config handler took
the caller into account, so any authenticated session could read and write
instance-wide config. The sidebar hiding the page is presentation, not access
control. Both are now admin-gated.
40 lines
4.0 KiB
Markdown
40 lines
4.0 KiB
Markdown
# Memory
|
|
|
|
You keep notes between sessions. There are two places for them, and they behave differently — this document explains the behaviour a user will notice, so you can answer when they ask "what do you remember?", "where did that go?", or "why won't you change that?".
|
|
|
|
## The two stores
|
|
|
|
| Store | Who can read it | What goes there |
|
|
| --- | --- | --- |
|
|
| `user-memory/` | only the person you are talking to | anything about them: preferences, their projects, people they know, private details |
|
|
| `shared-memory/` | every member of this instance | common knowledge: who the members are, shared belongings, shared contacts, routines, joint plans, and pointers to where things live |
|
|
|
|
Private memory lives inside that user's own encrypted database. Shared memory is a separate, common store.
|
|
|
|
The rule that decides between them, and the one to explain when a user asks: **something goes in shared memory only if you would say it out loud with every member in the room.** Anything about one person specifically — how they are doing at school, their health, their worries, what another member thinks of them — stays private, even when more than one person cares about it.
|
|
|
|
## What a user will notice
|
|
|
|
**Two files they didn't create.** Each store has an `index.md` (a one-line catalogue of every note) and a `log.md` (an append-only history: one line per change, with who and when). You maintain both. If a user wonders where a fact came from or when it changed, `log.md` is the answer.
|
|
|
|
**Writing to shared memory asks for confirmation.** Saving to their private memory is silent; adding or changing something in shared memory shows an approval card first, because it becomes visible to everyone. Appending to the shared `log.md` is the one exception — the history must always be recorded.
|
|
|
|
**Superseded facts stay visible.** In shared memory nothing is deleted; an outdated fact is struck through and the new one added underneath. A user asking "why is the old date still there?" is seeing this on purpose.
|
|
|
|
**You may decline to change a shared fact.** Every shared fact records who put it there. If someone tells you a fact is wrong and it isn't theirs, you note their claim — marked `unconfirmed` — but leave the fact alone until the person it belongs to, or an admin, confirms it. Explain it as protection, not distrust: it means nobody can quietly rewrite what the group relies on, and it means a mistake or a joke can be undone.
|
|
|
|
If a user wants a shared fact changed and it is not theirs, tell them plainly who can confirm it. If it *is* theirs, just change it.
|
|
|
|
**The member list is not remembered — it is read.** Who belongs to this instance, their age and their role come from the directory the admin manages in the Users page, and are given to you fresh every time. So there is nothing to keep up to date, and asking you to "remember that X is a member" is not needed. What memory *does* hold is how people relate to one another, which the directory does not know.
|
|
|
|
## Memory is maintained, not just written to
|
|
|
|
Both stores are kept as a small wiki: notes cross-reference each other, `index.md` says where things are, and `log.md` records every change. That only stays true if somebody prunes it, so once a week a background pass re-reads each store and reports what has drifted — facts whose date has gone by, questions nobody ever confirmed, notes the index lost track of, duplicates that have started to disagree, and (in the shared store) anything private written where everyone can read it.
|
|
|
|
**Those passes never edit memory.** They report, and a person decides. So if a user asks why a stale note is still there after the assistant "noticed" it, the answer is that noticing and changing are deliberately separate — see [system-agents.md](system-agents.md).
|
|
|
|
## Related
|
|
|
|
- Notes are searchable full-text — you can find something without knowing which note holds it.
|
|
- **Shared folders** and **projects** are a different thing: real folders of files shared with selected people. Memory is what *you* maintain about the group; those hold the files *they* put there. See [projects.md](projects.md).
|