أي ملف يفعل ماذا؟
Which File Does What?
ما هذه الصفحة، وماذا تحتوي.
الجلسة: محادثة واحدة بكل ما دار فيها. تفتحها وتغلقها وتعود إليها لاحقًا. فصل العمل إلى جلسات يبقي كل موضوع نظيفًا، ويجعل الرجوع خطوة إلى الوراء ممكنًا عند الخطأ. ستستعمل هنا hermes journey list، والقراءة نحو 5 دقائق. انتبه: الجلسة الطويلة جدًا تُنسي الوكيل بدايتها وتكلّف أكثر. ابدأ جلسة جديدة لكل مهمة مختلفة.
SOUL.md vs USER.md vs MEMORY.md vs AGENTS.md — a one-page map of the agent's files, who writes each one, and when the agent actually sees them
نتائج مأخوذة من هذه الصفحة، لا من قالب.
- تعرف ما الجلسة ولماذا قد تحتاجه.
- تنفّذ
hermes journey listوتفهم ما يحدث بعدها. - تقرأ الجدول وتأخذ منه السطر الذي يخصّك فقط.
كما تظهر تمامًا داخل Hermes.
hermes journey list
انتقل مباشرة إلى ما تحتاجه.
بلا اختصار أو حذف.
النص أدناه منقول من المصدر الرسمي بالإنجليزية حتى تبقى الأوامر والأسماء دقيقة كما هي. قبل كل قسم شرح عربي يوضّح ما بداخله.
"I told my agent something and it forgot." "Which file is my agent's brain?" "I edited SOUL.md — why doesn't it know my name?" These questions all come down to the same thing: Hermes Agent is shaped by several markdown files, and each one has a different job. This page maps them all in one place. For depth on any of them, follow the links to Persistent Memory, Personality & SOUL.md, and Context Files.
The Master Table
جدول مرجعي. لا تقرأه كله، ابحث عن السطر الذي يخصّك فقط.
| File | What it holds | Who writes it | When the agent sees it | Where it lives |
|---|---|---|---|---|
| SOUL.md | The agent's primary identity — personality, tone, communication style, what to avoid stylistically | You. Hermes seeds a starter file automatically if one doesn't exist; existing files are never overwritten | Slot #1 of the system prompt, at session start | ~/.hermes/SOUL.md (or $HERMES_HOME/SOUL.md with a custom home) — never the working directory |
| USER.md | User profile — your name, role, preferences, communication style, expectations | The agent, via the memory tool (you can gate saves with write_approval, or edit entries via hermes journey edit) | Injected into the system prompt as a frozen snapshot at session start | ~/.hermes/memories/ |
| MEMORY.md | Agent's personal notes — environment facts, project conventions, tool quirks, things learned | The agent, via the memory tool (same gating and editing options as USER.md) | Injected into the system prompt as a frozen snapshot at session start | ~/.hermes/memories/ |
| AGENTS.md | Project instructions, conventions, architecture — commands, ports, paths, repo-specific workflows | You (or whoever authors the project) | Loaded into the system prompt at startup from your working directory; nested copies are discovered progressively as the agent navigates subdirectories | Project working directory + subdirectories |
| .hermes.md / HERMES.md | Project instructions, like AGENTS.md but Hermes-specific and highest priority | You | Loaded into the system prompt at startup (first match wins over AGENTS.md) | Your project — discovery walks up to the git root |
A useful shorthand:
- SOUL.md is who the agent is — if it should follow you everywhere, it belongs here.
- USER.md is who you are — the agent maintains it for you.
- MEMORY.md is what the agent has learned — it maintains this itself too.
- AGENTS.md (or
.hermes.md) is what the project needs — if it belongs to a project, it belongs here.
"Why did it forget what I just said?"
شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه. تذكير: محادثة واحدة بكل ما دار فيها. تفتحها وتغلقها وتعود إليها لاحقًا.
Memory (MEMORY.md and USER.md) is injected into the system prompt as a frozen snapshot captured once at session start — when the agent saves something mid-session, the change is persisted to disk immediately but won't appear in the system prompt until the next session starts. This is intentional: it preserves the LLM's prefix cache for performance, and tool responses always show the live state, so nothing is lost — start a new session and the updated memory is there. Full details in How Memory Appears in the System Prompt.
Common Mix-Ups
أوامر تكتبها في الطرفية. افهم ما يفعله الأمر قبل نسخه. الأوامر هنا: hermes journey list.
"I put facts about myself in SOUL.md, but USER.md stayed empty"
SOUL.md and USER.md are separate systems that never feed each other. SOUL.md is a personality file you edit directly — it shapes tone and identity, and its content is injected verbatim as slot #1 of the prompt. USER.md is part of persistent memory and is written by the agent through the memory tool. If you want facts about yourself in USER.md, tell the agent ("remember that I prefer concise answers") and it saves them — editing SOUL.md won't populate memory, and memory entries won't change the persona. Use SOUL.md for durable voice and personality guidance; leave preferences and profile facts to memory. See What should go in SOUL.md? and Two Targets Explained.
"I told it my name mid-session and it acted like it never heard it"
If the agent saved your name to memory, the save worked — check with the memory tool's responses or hermes journey list. What you're seeing is the frozen-snapshot rule above: the system prompt doesn't refresh mid-session, so the injected memory block still shows the session-start state. The agent can still use what you told it within the current conversation (it's in the context), and the saved entry will be in the system prompt from the next session onward. The same applies to edits you make to SOUL.md or AGENTS.md while a session is running: context is assembled at session start, so restart the session to pick up changes.
سؤالان إجاباتها كلها في هذه الصفحة.
كل خيار اسم حقيقي من توثيق Hermes. حتى الخيارات الخاطئة حقيقية، لكنها من صفحات أخرى.