Memory in EverOS OSS is partitioned by ownership and routed automatically. The directory layout is self-explanatory by design: open memory-root/ and the structure tells you what lives where without needing to read a schema.
Three Tracks
| Track | Routed from | Directory | Answers |
|---|
| User Memory | role="user" sender | users/<user_id>/ | Who is this user? What have they said? |
| Agent Memory | role="assistant" sender | agents/<agent_id>/ | What has this agent learned? What can it do? |
| Wiki Memory (coming soon) | User upload or global config | knowledge/ | What does the system know about the world? |
role. No manual routing is required.
User Memory
User Memory captures everything about a specific user across their interactions. The key design is multi-granularity coexistence — four types of memory exist side by side, each serving a different retrieval need.
users/u_jason/
├── user.md User Profile · identity, goals, preferences, values
├── behaviors.md Procedural · behavioral history, proactive service input
├── episodes/ Episodic · narrative summaries (daily append)
│ └── episode-2026-04-22.md
├── atomic_facts/ AtomicFact · independently retrievable facts (daily append)
│ └── fact-2026-04-22.md
└── foresights/ Foresight · time-bounded plans and predictions (daily append)
└── foresight-2026-04-22.md
| Type | Form | What it stores |
|---|
user_profile | Single file, in-place update | Aggregated portrait — identity, preferences, values |
behaviors | Single file, in-place update | Behavioral patterns for proactive service |
episode | Daily append log | Narrative summary of a conversation segment |
atomic_fact | Daily append log | A single, independently retrievable extracted fact |
foresight | Daily append log | A time-bounded plan or prediction about the user |
episode and atomic_fact represent different granularities of the same conversation. Neither replaces the other — both are retained. At retrieval time, mRAG selects the granularity that best fits the query. See Retrieval.
Agent Memory
Agent Memory captures what an agent has learned and who it is. The key design is the experience feedback loop and the separation of stable identity from dynamic experience.
agents/agent_zhangsan/
├── soul.md Identity · core persona, values, behavioral boundaries
├── agent.md Playbook · behavior rules, workflows, user feedback
├── tools.md Declaration · tool capabilities and constraints
├── skills/ Procedural · reusable skills distilled from cases
│ └── skill_contract_risk_scan/
│ ├── SKILL.md T1 — entry point, lightweight description
│ ├── references/ T3 — read on demand
│ └── scripts/ T3 — execute on demand
└── cases/ Episodic · execution traces (raw material)
└── case-2026-04-22.md
Identity files
| File | Layer | Purpose |
|---|
soul.md | Identity | Core persona, values, behavioral constraints — who the agent is |
agent.md | Playbook | Behavior rules, workflows, tool usage, user feedback — how the agent operates |
tools.md | Declaration | Declared tool capabilities and boundaries |
Experience files
| Type | Form | Purpose |
|---|
agent_case | Daily append log | Full execution trace — input, tool calls, decisions, outcome |
agent_skill | Named directory | Reusable skill distilled from a cluster of cases |
case and skill are the dynamic layer — accumulated and evolved automatically by the system.
The experience loop
execute task → record case (success or failure trace)
↑ ↓
reuse skill offline clustering
↑ ↓
└────────── distill skill ──┘
skills/ and you can see exactly what the agent knows how to do.
Why stable and dynamic layers are separated
An agent’s values and identity (soul.md) are maintained deliberately. Its experience (cases/, skills/) accumulates automatically. Keeping these separate ensures that a failed case doesn’t corrupt the agent’s core persona — identity is not overwritten by experience.
Skill file structure
Each skill is a directory with three tiers:
SKILL.md — entry point, lightweight description and usage instructions (always loaded)references/ — supporting material, loaded on demandscripts/ — executable scripts, run on demand
This progressive disclosure design means an agent never loads all skill detail into context at once — it loads the entry point and pulls deeper tiers only when needed.
Wiki Memory
Wiki Memory is not yet available in the current release. The design and directory layout are documented here for reference — the API and ingestion pipeline are coming in a future version.
knowledge/
└── <knowledge_entry_id>.md KnowledgeEntry · extracted from multimodal sources
| Property | Detail |
|---|
| Ownership | Global — not bound to any specific user or agent |
| Sources | User-uploaded files, crawled pages, internal wikis, product manuals |
| Extraction | evercore.Knowledge.KnowledgeExtractor unifies heterogeneous sources (PDF, image, video, URL) into KnowledgeEntry records |
| Boundary | Factual knowledge, not experiential memory — “what is known,” not “what happened” |
users/ would pollute personal memory. Placing it in agents/ would bind it to a specific agent. knowledge/ is a separate track precisely to avoid both problems.
Zero-Config Identity
There is no “create user” or “register agent” API. The first time a message is written with a given sender_id, EverOS OSS creates the owner directory on demand. The same sender_id aggregates automatically across sessions.
Naming is the caller’s responsibility — EverOS OSS does not generate or manage identifiers.
The Three Tracks as a Cognitive System
| User Memory | Agent Memory | Wiki Memory |
|---|
| Answers | Who is this user? What did they experience? | What can this agent do? What has it learned? | What is true about the world? |
| Cognitive analog | Autobiographical memory | Procedural memory | Semantic memory |
| Ownership | Single user | Single agent | Global |
| Evolved by | User interactions | Execution experience | External ingestion |
| Example query | ”What did Jason say last time?" | "How do I scan a contract for risk?" | "What does GDPR require?” |
