docs(architecture): document memory engine family
This commit is contained in:
1 parent
0e53485ea1
commit
df41aa27fb
2 files changed
+51
No files matched your search
@@ -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."}}
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user