Ymem

Ymem is a general-purpose agent memory kernel — open-source, benchmarkable, and host-app-agnostic. It provides the core memory operations an AI agent needs (ingest, retrieve, consolidate, explain) without making assumptions about how the agent is exposed to users.

The project is in early design and prototyping. The repository is public so the contracts, evaluation methodology, and reference implementation can evolve in the open.

What Ymem Is

Ymem is a runtime library and a set of contracts. The intended position:

your app / agent
        |
        v
Ymem (kernel)         <- this repo
        |
        v
storage + retrieval + LLM + benchmarks

Core ideas:

• Generic memory objects. MemoryRecord, MemoryQuery, MemoryResult, ProvenanceRef, MemoryTrace, MemoryDiff, EvalCase. None of them refer to a specific product surface.
• Explainable retrieval and consolidation. Every result carries provenance. Every consolidation produces a reviewable MemoryDiff rather than silently mutating canonical state.
• Benchmark-first. A kernel is only as good as its evaluation. Ymem ships adapters for public benchmarks (LongMemEval, MemoryAgentBench, LoCoMo, MemoryArena) and supports private fixtures from host apps.

What Ymem Is Not

Ymem deliberately does not include:

• a UI, audit dashboard, or review surface (those belong in host apps);
• product-specific concepts like ContextPack or workspace ingestion;
• opinions about which embedding model, vector DB, or LLM you use (everything is plugged in through interfaces).

Architecture

External Benchmarks
LongMemEval / MemoryAgentBench / LoCoMo / MemoryArena
        |
        v
+--------------------------------------------------+
| Ymem                                             |
|--------------------------------------------------|
| TS runtime core                                  |
| Generic memory objects                           |
| Retrieval / dedup / update / forgetting          |
| Dream / consolidation candidates                 |
| Eval runner + Python benchmark adapters          |
+----------------------+---------------------------+
                       |
                       | MemoryProvider API
                       v
                 host applications

See docs/design/split-plan.md for the full design, including the public API surface, evaluation plan, and integration contract with host apps.

Host Applications

The first host app is ZhiOne, a local-first context engine for personal and team knowledge. Ymem is designed so ZhiOne is one of many possible hosts, not the only one.

Research Inputs

Algorithm iteration is driven by an external knowledge base, awesome-agent-memory, which tracks papers, products, and architecture proposals relevant to agent memory. New ideas flow into Ymem as sandboxed experiments and graduate through ADR review.

awesome-agent-memory  ->  Ymem  ->  zhione
   (upstream notes)    (kernel)   (host product)

Repository Status

This repository currently contains:

• The split plan that established Ymem's boundaries with host apps.
• License, contribution, and code-of-conduct files copied from ZhiOne.

There is no production code yet. The first implementation milestones are listed in ROADMAP.md. Contributions are most useful when they:

• sharpen the MemoryProvider interface;
• propose evaluation fixtures or benchmark adapters;
• prototype storage / retrieval / consolidation modules behind the interface;
• identify risks around privacy, provenance, or agent autonomy.

License

Ymem is licensed under the Apache License 2.0. See LICENSE.