oGMemory Architecture
oGMemory is a context lifecycle engine designed for agents. It manages the key boundaries of the agent loop, including what enters the context window, what is persisted, what is compressed and archived, and what can be recalled in subsequent sessions.
Architecture Overview
The core design of oGMemory is to manage context as data with a lifecycle, rather than treating it as simple vector retrieval text. The system consists of the access layer, service orchestration layer, write link, read link, ContextFS, session layer, and asynchronous index layer.
ContextFS is a unified context storage abstraction for the upper layer. It can be implemented using AGFS or DB-first storage. DB-first refers to using database tables to directly store semantic nodes, content, abstracts, overviews, relationships, and metadata, which is an alternative to the primary storage form of AGFS. The upper-layer extraction, write policy, retrieval, and compression processes do not need to be aware of whether the underlying storage is AGFS or DB-first.
Agent / Plugin
|
| HTTP REST / Python SDK
v
+------------------------------------------------------------------+
| HTTP API |
| Lifecycle entry, authentication, and RequestContext construction |
+-------------------------+----------------------------------------+
|
v
+--------------------------------------------------+
| MemoryService |
| compose / after_turn / compact / dispose |
+-------------------------+------------------------+
|
+-----------------+-----------------+
| |
v v
+-----------------------------------+ +-----------------------------------+
| Write link | | Read link |
| Extraction -> Policy-based routing| | Intent -> L0/L1/L2 |
| -> Atomic write | | -> Scoring -> Assembly |
+-------------------+---------------+ +-------------------+---------------+
| |
+-----------------+-----------------+
|
v
+----------------------------------------------------------------------------+
| ContextFS |
| Semantic nodes, content, abstracts, overviews, relationships, and metadata |
+-------------------------+--------------------------------------------------+
|
+-----------------+-----------------+
| |
v v
+---------------------+ +----------------------------+
| Session layer | | Asynchronous index layer |
| SessionBuffer | | OutboxWorker |
| Archive / Compact | | L0/L1/L2 Index |
+---------------------+ +----------------------------+
|
v
+--------------------------------------------------+
| Storage backend |
| AGFS / DB-first + Vector DB |
+--------------------------------------------------+Writing to a Data Stream
The path from the end of an agent turn to the time when a conversation can be retrieved is as follows:
End of agent turn
|
v
after_turn
|
v
Incremental extraction
|
v
CandidateMemory[]
|
v
PolicyRouter
Selecting a write policy based on the context type
|
v
ContextWriter
Atomic write to ContextFS
The underlying layer can be AGFS or DB-first.
|
v
OutboxEvent
|
v
Index Worker
Generating L0, L1, and L2 vector indexesThe write link focuses on the following four aspects:
| Target | Description |
|---|---|
| Extraction | Identifies candidate contexts such as profile, preference, event, and skill from conversations. |
| Routing | Selects the merge, aggregate, or append write policy based on the context type. |
| Persistence | Writes data to the primary storage through ContextFS. The underlying layer can be AGFS directory files or DB-first database tables. |
| Indexing | Generates L0, L1, and L2 vector indexes in the background through Outbox after the write is complete. |
Data Stream Reading
The path from the time when a user query enters oGMemory to the time when the agent context is injected is as follows:
User query
|
v
compose
|
v
Intent recognition and query planning
|
v
L0, L1, and L2 hybrid vector search
|
v
L0 and L1 hits as the directory entry
|
v
Hierarchical expansion to L2 content
|
v
Reads the content from the source ContextFS.
The underlying AGFS/DB-first is transparent to the read link
|
v
Sorting, deduplication, and budget control
|
v
Assembles into injectable contextThe read link does not perform a single-layer top-k search. oGMemory indexes the abstract, overview, and full content simultaneously.
| Level | Content | Purpose |
|---|---|---|
| L0 | Short abstract | Quickly locates the topic and serving as the directory roadmap. |
| L1 | Structured overview | Determines relevance and content scope. |
| L2 | Full content | Provides detailed evidence that can be finally injected. |
This hierarchical retrieval method can reduce the missing recall caused by the dilution of long text embedding signals. L0 and L1 are responsible for locating, and L2 is responsible for providing complete information.
Regardless of whether the primary storage uses AGFS or DB-first, the read link retrieves the content through ContextFS. The vector database is only responsible for the index view required for candidate recall and ranking.
Lifecycle Model
oGMemory organizes context capabilities based on the agent running phase. Each phase only processes the tasks that are suitable for that phase, avoiding putting all logic into a single retrieval or extraction.
| Phase | Occasion | Main Entry | Purpose |
|---|---|---|---|
| 1. Message arrival | Before agent inference | compose | Parses the current question and prefetches candidate contexts. |
| 2. Inference preparation | Assembles the context window. | compose | Injects profiles, archives history, session status, and retrieval evidence. |
| 3. Tool use | Before and after tool invocation | tool usage collector | Collects tool invocation statistics to provide input for subsequent extraction and observation. |
| 4. End of a round | After the agent completes a round | after_turn | Accumulates new messages and extracts and writes them to long-term memory when the threshold is reached. |
| 5. Compression management | The context is close to the upper limit or is explicitly compacted. | prepare_compaction / compact | Extracts the unprocessed content, archives the session, and returns the compressed summary. |
| 6. Session closure | The session ends. | dispose | Updates the remaining messages and clears the active session. |
Context Transfer in the Lifecycle
Dialog message
-> SessionBuffer
-> Incremental extraction
-> ContextFS node
(Primary storage of AGFS or DB-first)
-> Outbox asynchronous index
-> Hierarchical retrieval
-> Compose injection
-> Compact/Dispose archivingContext Types
oGMemory distinguishes context types based on information semantics. Different types have different lifecycles, write policies, and scopes.
| Type | Purpose | Write Method | Typical Scope |
|---|---|---|---|
| profile | Stable user identity information, such as name, occupation, and location | Merging | user |
| preference | User preferences, such as coding style and tool preferences | Merging by topic | user |
| entity | Entity facts such as people, projects, organizations, and locations | Merging by entity | user |
| event | Historical events with time boundaries | Append write | user |
| case | Cases and experience of agents in solving problems | Append write | agent |
| pattern | Behavior patterns observed from interactions | Merging by topic | user |
| skill | Workflow and skills that can be reused by agents | Merging by skill | agent |
| tool | Tool usage experience, parameter suggestions, and failure modes | Merging by tool | agent |
These types are declared by the YAML schema. The schema determines the extracted fields, owner scope, catalog template, and write mode. Therefore, users can add custom context types without modifying the main process.