aws-samples / aws-samples/sample-agent-greenhouse

Consolidate fragmented memory system into a single foundation/memory/ package

Open
#5 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.