Memory Types

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?
Knowledge Wiki	Document upload (`/api/v1/knowledge`)	`knowledge/`	What reference material has the system been given?

User and Agent writes are routed automatically by message role; the Knowledge Wiki is populated by explicit document upload.

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 patterns (supported, not yet produced)
├── 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 (supported by the writer, but no shipped strategy produces it yet)
`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

These files are the stable layer — maintained intentionally by humans, not automatically updated by the system.

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  ──┘

Each execution produces a case. Cases are periodically clustered into skills — generalized, reusable approaches to a class of task. The result is an agent that compounds capability over time, with a transparent record of what it has learned: open 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 demand
scripts/ — 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.

Knowledge Wiki

The Knowledge Wiki answers a different question from User and Agent Memory: not “what did this user experience” or “what has this agent learned,” but “what reference material has the system been given.” It holds documents you deliberately upload (PDF, DOCX, Markdown, and more), which an LLM extracts into a searchable topic library.

knowledge/
└── <category>/
    └── <Document_Title>_<doc_id>/
        ├── index.md        document metadata + LLM summary
        ├── 1_<topic>.md    extracted topic with full content
        └── _original/      the original uploaded file, unchanged

Property	Detail
Ownership	Global, isolated per `app_id` / `project_id`, not bound to a user or agent
Sources	Uploaded files: PDF, DOCX, HTML, images, audio, plain text
Structure	LLM-extracted hierarchy: L0 category, L1 document, L2 topic
Boundary	Reference material you provide, not experience extracted from conversation

Placing uploaded reference docs in users/ would pollute personal memory; placing them in agents/ would bind them to a specific agent. knowledge/ is a separate track precisely to avoid both problems. See Knowledge Wiki for the full upload, taxonomy, and search reference.

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	Knowledge Wiki
Answers	Who is this user? What did they experience?	What can this agent do? What has it learned?	What do the uploaded reference docs say?
Cognitive analog	Autobiographical memory	Procedural memory	Semantic memory
Ownership	Single user	Single agent	Global
Evolved by	User interactions	Execution experience	Document upload
Example query	”What did Jason say last time?"	"How do I scan a contract for risk?"	"What does GDPR require?”

Three tracks, physically isolated, linked by reference: a complete cognitive coordinate system for an AI agent.

Introduction

Getting Started

Core Concepts

Advanced

Three Tracks

User Memory

Agent Memory

Identity files

Experience files

The experience loop

Why stable and dynamic layers are separated

Skill file structure

Knowledge Wiki

Zero-Config Identity

The Three Tracks as a Cognitive System

​Three Tracks

​User Memory

​Agent Memory

​Identity files

​Experience files

​The experience loop

​Why stable and dynamic layers are separated

​Skill file structure

​Knowledge Wiki

​Zero-Config Identity

​The Three Tracks as a Cognitive System

Three Tracks

User Memory

Agent Memory

Identity files

Experience files

The experience loop

Why stable and dynamic layers are separated

Skill file structure

Knowledge Wiki

Zero-Config Identity

The Three Tracks as a Cognitive System