docs(architecture): document memory engine family

This commit is contained in:
sam committed 2026-08-15 23:38:34 +10:00
1 parent 0e53485ea1
commit df41aa27fb
2 files changed
+51

No files matched your search

+1
View File
@@ -1,2 +1,3 @@
{"id":"int-ca573b1f243d5e820077aadb21af8595","kind":"field_change","created_at":"2026-08-15T12:27:33.967613847Z","actor":"Sam Catlow","issue_id":"archie-core-1786637491053-48-fe78cd53","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Verified against current main: Route/RouteStream reject unrecognized slash commands before any LLM call (gateway.go:299-318, 449-462), /start is deterministic in both gateway and Telegram handlers, and full test matrix from acceptance criteria exists (gateway_test.go:106-133, gateway_stream_test.go:54-88, telegram_test.go:135-157). Confirmed by fresh code-tracing pass, not just prior user experience."}}
{"id":"int-73ca4d209481e52e20c00c128fc6a3ca","kind":"field_change","created_at":"2026-08-15T12:41:34.047451864Z","actor":"Sam Catlow","issue_id":"archie-core-1786748942519-17-5999d55b","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
{"id":"int-2193ae15ea3e5922294ec78dffe4958a","kind":"field_change","created_at":"2026-08-15T13:36:38.960683238Z","actor":"Sam Catlow","issue_id":"archie-core-1786637489985-8-13b9d8a8","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Documented the memory engine contract, owning manager, lifecycle/failure isolation, and third-party trust boundary in ARCHITECTURE.md; focused memory tests pass."}}
+50
View File
@@ -274,6 +274,56 @@ of this rule: the generic plugin method set, the shared agent-instruction
source, and the requirement that engine interfaces have domain behavior plus an
owning registry or manager.
### Memory engine family
The current memory implementation is an engine family, not a collection of
independent memory tools. `internal/memory.MemoryProvider` is the typed contract
for built-in and external providers. It requires a provider name and availability
check, session initialization, and tool-schema export. Optional capability
contracts add system-prompt contributions, prefetch, conversation-turn sync,
tool-call handling, and shutdown. Lifecycle hooks in `internal/memory/lifecycle.go`
cover turn start, session end and switching, pre-compression, memory writes, and
delegation.
`internal/memory.Manager` is the owning family manager and the only entry point
that agent lifecycle code should use. It owns the built-in provider and, in the
current implementation, permits at most one external provider. It merges schemas
from available providers, indexes tool ownership, routes calls, validates
provider configuration through provider-owned schemas, and serializes background
write synchronization. Providers do not register callbacks or tools directly on
the daemon.
The manager defines the lifecycle and failure-isolation contract:
- construction starts the bounded background synchronization worker;
- initialization attempts every active provider and returns the first error only
after all providers have been attempted;
- lifecycle hooks are dispatched asynchronously, with provider errors and panics
recovered so a failing hook cannot interrupt the agent loop;
- shutdown stops accepting new synchronization work, drains until the caller's
context deadline, records abandoned work after a timeout, and shuts providers
down in reverse registration order while still attempting every provider;
- provider availability is checked before schemas and tool ownership are exposed,
so an unavailable provider is isolated from normal dispatch rather than taking
down the family.
A memory backend is not trusted merely because it implements
`MemoryProvider`. The built-in file-backed provider runs in the daemon's trusted
process. A third-party backend may run in-process only when the operator has
explicitly trusted it with daemon privileges. An untrusted or out-of-process
backend must cross a versioned, scoped protocol owned by the memory manager; if
confidentiality or integrity depends on process isolation, it must run in a real
container sandbox. A subprocess boundary alone is not a security boundary, and
the backend must never receive `*daemon.Daemon`, a service locator, unrestricted
host files, or credentials by virtue of being a memory provider.
These are the current `internal/memory` contracts and wiring. They do not close
the OPEN placement, authoritative-record, retrieval, access-enforcement, or
provenance decisions listed in
[`docs/architecture/migration-decisions.md`](docs/architecture/migration-decisions.md#5-memory-placement-and-storage),
nor do they change the four required scopes documented in
[`docs/architecture/agent-system.md`](docs/architecture/agent-system.md#memory-scopes).
## Key Design Decisions
1. **Environmental constraints over prompt rules.** The gate, test-file