Memory for an AI Agent: From Complexity to 300 Lines of Code

AI agent memory is one of the most complex problems when building autonomous systems. Developer Nikolay Gusev spent months searching for a working solution and shared how he achieved simplicity and scalability at the same time.

MemPalace and the first mistake

It all started with an ambitious idea — MemPalace, a memory system inspired by the architecture of medieval palaces. It looked smart on paper, but in practice created 58 thousand duplicate fragments and turned into an impenetrable maze. Too many layers of abstraction, too much magic. The agent got lost in its own memory.

The path to simplicity

After MemPalace, the author simplified the stack to four components: MEMORY.md (main database), USER.md (user context), SQLite state.db (state), HippoRAG (search) and wiki files (structured data). But even this seemed excessive. The right move was writing `findings_to_wiki`, a simple 300-line Python script that automatically saves structured analyses (marked with headings like `## Findings`) into markdown files and transforms them into wiki pages. No frameworks, no ORM, just files and text.

Scaling: ClickHouse

When there's only one agent, file storage works perfectly. But if you need to support 100+ users simultaneously, you need a real database. This is where ClickHouse 24.x comes into play. Key features:

• Vector search via the `cosineDistance()` function — fast search for semantically similar memories
• Text search with `tokenbf_v1` index — full-text search across memory
• Partitioning by user_id — user data isolation built into the database
• TTL for automatic deletion — old records are deleted without manual intervention

ClickHouse performs analytics and search across millions of records in milliseconds. For agent memory, this is more than sufficient.

What this means

The key takeaway: don't start with scaling. Solve the problem simply (files, markdown, 300 lines of code), then scale only if needed. Nikolay demonstrated that the best engineering path is from complexity to simplicity, not the other way around.