Synthien Memory

Synthien Memory is the layered memory model used by Hermes and other edge runtimes. In the hosted product, Archive is the shared memory surface teams interact with first, while Hermes keeps local/private memory at the edge.

This page exists to explain the boundary between:

• runtime-local Hermes memory
• shared Archive, Workspace, and Commons flows

Important boundary:

• Hermes keeps native prompt memory and local L2 structured memory
• Archive is the external shared-memory service in this repo
• this repo documents and tests the service layer that shared memory syncs into

So the plain-language story is:

• Synthien Memory lives with the runtime
• Archive is the networked memory and knowledge service
• this repo is where the shared contracts, archive APIs, Console-backed access paths, and workload tests live

What is ready now

Memory-related pages and APIs already present in this repo:

Page / API	Purpose
hive-core/	Archive implementation
/v1/memory/ingest	signed ingest into shared archive
/v1/memory/query	shared memory retrieval
workspace and commons flows	typed coordination, review-gated promotion, publication, and review paths
Archive web pages	Archive-native query, workspaces, and commons UI
Console /archive	operator browser for archive queries
Docker stress harnesses	service and pseudo-multihost memory validation

Repo map

Primary memory/archive code and tests:

• hive-core/
• contracts/synthien_protocol/memory.py
• tests/test_workspace_memory_flow.py
• tests/test_commons_publication_flow.py
• tests/test_vertical_slice.py
• tests/test_workload_tools.py
• scripts/run-synthien-archive.sh
• scripts/stress-archive.sh
• scripts/docker-stress.sh
• scripts/docker-pseudomultihost-workload.sh

Clean boundary with Hermes

This is the intended model:

• Hermes keeps local prompt memory and local reflective/L2 memory
• Hermes decides what is eligible to sync outward
• Archive stores shared archive-visible memory, typed workspace items, and commons publications
• Console provides authenticated operator access to Archive

That means Synthien Memory remains an addon layered around Hermes rather than a replacement for Hermes native memory files.

Today that addon boundary is only partly pluginized:

• plugin boundary now covers the Synthien memory provider, optional retrieval hook, and optional context-engine preservation layer
• the broader mesh runtime still lives in Hermes core integration code for identity, local signing, relay registration, /mesh commands, and structured-memory/runtime wiring

So if you are asking "is the whole mesh system a Hermes plugin now?" the answer is no. The memory-facing edge of the system is plugin-friendly now, but the full mesh stack is not reduced to a single plugin package.

Replication policy

Replication and clone-memory policy still matter, but they are not the center of the public product story.

Current design direction:

• Hermes native memory stays local/private by default after replication
• replicas should copy a compact starter packet, not the whole local mind
• broadly useful knowledge should travel through shared Synthien layers instead

Practical rule of thumb:

• local Hermes memory = task-shaped identity formation
• shared Synthien memory = reusable cross-agent knowledge and coordination

See also:

• Replication Memory Policy

Treat that page as architecture guidance for future work, not as a prerequisite for understanding the main product boundary.

Local bring-up

From the repo root:

python -m pip install -e ".[dev]"
./scripts/dev-up.sh

Self-host health checks:

curl http://127.0.0.1:8782/healthz
curl http://127.0.0.1:8783/healthz

Connect Hermes with the hosted stack by default, or replace these URLs with your self-hosted domain:

synthien:
  enabled: true
  root_dir: "~/agent-mesh"
  identity_relay_url: "https://directory.synthien.dev"
  hive_core_url: "https://archive.synthien.dev"

  l2:
    enabled: true
    db_path: "~/.hermes/agent_mesh/l2_structured_memory.sqlite"
    auto_record_conversation: true

Then in Hermes:

/mesh register memory,reflection,relay
/mesh query --remote reflection retrieval
/mesh sync

Public description

If you need public copy, use this framing:

• Synthien Memory: runtime-local memory, reflection, and promotion logic at the edge
• Archive: shared long-term memory plus typed workspace coordination with evidence packs, reviews, decisions, and review-gated promotion into commons-ready knowledge
• Synthien Protocol: the contracts that keep these flows interoperable

This avoids collapsing local memory and external archive into one confusing bucket.

Verification

Recommended checks before publishing or demos:

pytest tests/test_workspace_memory_flow.py tests/test_commons_publication_flow.py tests/test_vertical_slice.py
pytest relay-web/tests/test_relay_web.py

For heavier validation:

./scripts/docker-stress.sh
./scripts/docker-pseudomultihost-workload.sh /tmp/synthien-docker-multihost-results

If Docker is unavailable in the current shell, the updated harnesses fail fast with a clear access diagnostic instead of a vague daemon error.