@samitouri / QOSami_Agents_Zero
Code Commits Issues Pulls Sessions CI/CD
main
main
md 142 lines 5.13 KB
Rendered Raw
1 # Memory Guide
2
3 Agent Zero can remember useful facts, solutions, preferences, and imported
4 knowledge so future chats do not always start from zero.
5
6 That power needs curation. Long-term AI memory is not a solved problem, even for
7 large AI labs and companies. A memory system can help the agent become more
8 useful, but it can also preserve stale assumptions, wrong conclusions, old test
9 data, or instructions that no longer fit. A sustainable memory system needs some
10 human gardening.
11
12 When Agent Zero does something unexpected, keeps repeating a bad habit, or seems
13 strangely confident about the wrong thing, Memory is one of the first places to
14 look.
15
16 ## Open Memory
17
18 Open **Memory** from the dashboard or sidebar.
19
20 ![Memory dashboard](../res/usage/memory-dashboard.png)
21
22 The dashboard shows remembered entries and imported knowledge chunks. Each row
23 has metadata, a content preview, copy and delete actions, and a detail view.
24
25 ## Search And Filter
26
27 Use the controls at the top to narrow what you are looking at.
28
29 ![Memory dashboard controls](../res/usage/webui/memory-dashboard-controls.png)
30
31 The most useful controls are:
32
33 - **Memory Directory:** choose the memory store you want to inspect.
34 - **Area:** filter between `main`, `fragments`, `solutions`, and `skills`.
35 - **Search:** find memories related to a phrase, behavior, project, tool, error, or preference.
36 - **Threshold:** adjust how strict the similarity match should be.
37 - **Limit:** control how many results are returned.
38 - **Clear:** reset the filters.
39
40 Start with ordinary words. If Agent Zero keeps using the wrong command, search
41 for the command. If it keeps assuming the wrong project rule, search for the
42 rule, client name, repo name, or phrase it keeps repeating.
43
44 ## Inspect And Edit
45
46 Click a memory row to open its details.
47
48 ![Memory editing](../res/usage/memory-editing.png)
49
50 In the detail view you can:
51
52 - read the full content;
53 - check whether it came from conversation memory or imported knowledge;
54 - copy the memory with metadata;
55 - copy only the content;
56 - edit the text;
57 - delete the entry.
58
59 Edit a memory when it is almost right but needs correction. Delete it when it is
60 wrong, obsolete, duplicated, too vague, or harmful to future reasoning.
61
62 ## What To Keep
63
64 Good memories are durable and useful:
65
66 - stable user preferences;
67 - project-specific conventions;
68 - commands that were verified and still apply;
69 - decisions that should persist across chats;
70 - known solutions to recurring problems;
71 - important constraints that are not obvious from files alone.
72
73 Good memory reads like a note you would happily give a future teammate.
74
75 ## What To Remove
76
77 Remove or rewrite memories that are likely to poison future processing:
78
79 - stale setup instructions;
80 - old paths, ports, service names, or commands;
81 - temporary experiments;
82 - failed guesses saved as facts;
83 - outdated project decisions;
84 - broad personality instructions that make the agent overcorrect;
85 - private data that should not have been remembered;
86 - memories copied from a confused or interrupted chat.
87
88 The danger is not that one bad memory always wins. The danger is that it becomes
89 one more piece of "evidence" nudging the agent in the wrong direction again and
90 again.
91
92 ## When Behavior Looks Wrong
93
94 Check Memory early when Agent Zero:
95
96 - keeps following an old instruction after you corrected it;
97 - keeps using a tool, path, or workflow you no longer want;
98 - mixes two projects together;
99 - remembers a false preference;
100 - repeats a wrong explanation;
101 - ignores current project instructions in favor of old context;
102 - acts as if a test result or setup step happened when it did not.
103
104 A good debugging loop is:
105
106 1. Search Memory for the repeated behavior or phrase.
107 2. Open likely entries and read the full content.
108 3. Edit entries that are useful but inaccurate.
109 4. Delete entries that are simply wrong.
110 5. Run the task again with a clear correction in the chat.
111
112 ## Use Project Memory For Project Context
113
114 Keep project-specific memories in the project where they belong. Client rules,
115 repository conventions, local commands, and workflow preferences should not leak
116 into unrelated work.
117
118 If Agent Zero is mixing contexts, check whether the memory belongs in global
119 memory or project memory. Moving from "global forever" to "this project only" is
120 one of the simplest ways to keep the system sane.
121
122 ## Be Careful With Bulk Cleanup
123
124 The dashboard can select multiple rows and copy, export, or delete them.
125
126 Before deleting many memories:
127
128 - export or back up important entries;
129 - search narrowly instead of deleting by broad category;
130 - delete obvious junk first;
131 - keep useful solutions even if they are old;
132 - avoid wiping imported knowledge unless you know how to rebuild it.
133
134 Memory curation is not about making the database empty. It is about keeping the
135 right signal and removing the noise that makes the agent less trustworthy.
136
137 ## Related
138
139 - [Usage Guide](usage.md): where Memory fits in the everyday Agent Zero workflow.
140 - [Projects Guide](projects.md): how project memory keeps client, repo, and task context separated.
141 - [Troubleshooting](troubleshooting.md): quick checks when Agent Zero behaves unexpectedly.
142 - [Backup And Restore](usage.md#backup-and-restore): what to do before large memory cleanup.