aws-samples / aws-samples/sample-agent-greenhouse
Consolidate fragmented memory system into a single foundation/memory/ package
- Dominant language
- Python
- Stars
- 21
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
The memory system is spread across multiple locations with overlapping responsibilities:
| File | Purpose |
|------|---------|
| `foundation/memory.py` | `SessionMemory` (in-memory list) + `WorkspaceMemory` (file-based `.md`) |
| `src/platform_agent/memory.py` | Older/alternative memory implementation |
| `foundation/memory_access_guard.py` | Namespace-based access control |
| `foundation/hooks/memory_hook.py` | Memory lifecycle integration |
| `foundation/hooks/memory_extraction_hook.py` | STM→LTM extraction pipeline |
| `foundation/hooks/consolidation_hook.py` | Memory consolidation |
This fragmentation makes it difficult for contributors to understand the full memory architecture and for users to know which memory class to use.
### Additional issue: rough token estimation
`SessionMemory` estimates tokens with `~4 chars per token for English text`. This undercounts for code-heavy conversations (~3 chars/token) and overcounts for non-English text. Since the compaction threshold depends on this estimate, inaccuracy can cause premature or delayed compaction.
## Proposed Solution
Consolidate into a single `foundation/memory/` package:
```
foundation/memory/
├── __init__.py # Public API: SessionMemory, WorkspaceMemory, LongTermMemory
├── session.py # SessionMemory (in-memory conversation history)
├── workspace.py # WorkspaceMemory (file-based .md persistence)
├── long_term.py # AgentCore LTM integration (STM→LTM pipeline)
├── access_guard.py # MemoryAccessGuard (namespace security)
└── extraction.py # Memory extraction strategies
```
Move memory-related hooks to use the consolidated package. Deprecate `src/platform_agent/memory.py` with a shim pointing to the new location.
For token estimation, either:
- Use `tiktoken` for accurate counts
- Or expose `chars_per_token` as a configurable parameter (default 4, recommend 3 for code-heavy use cases)
## Acceptance Criteria
- [ ] All memory code consolidated under `foundation/memory/`
- [ ] `src/platform_agent/memory.py` deprecated with import shim
- [ ] Token estimation is configurable or uses a proper tokenizer
- [ ] Memory hooks import from the consolidated package
- [ ] All existing memory tests pass against the new structure
- [ ] ARCHITECTURE.md updated to reflect the new layout
Contributor guide
Research direction
Start by reading foundation/memory.py, src/platform_agent/memory.py, the memory hooks, and the existing memory tests to map current imports and behavior. Consolidate the listed components under foundation/memory/, preserve compatibility through the deprecated shim, address configurable or tokenizer-based token estimation, and update ARCHITECTURE.md; done means the acceptance criteria are met and all existing memory tests pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100