HoloMem 0.1.0

A Modern 4-Stage Synthetic Memory

---

HoloMem – 4-Stage Synthetic Memory

Overview

HoloMem is a production-grade, multi-stage synthetic memory framework inspired by real cognition. Built for AI Agents, LLMs, Voice Assistants and more with advanced automation.

Stages:

1. Perception – Immediate, in-memory (RAM) context
   • Optional, not required
2. Sensory – Short-lived, per-user episodic memory
3. STM (Short-Term Memory) – Active conversation/session memory
4. LTM (Long-Term Memory) – Persistent archive

---

Key Features

• Direct, 4-stage architecture:

  • Perception (RAM) Sensory (Per User) → STM (All Users) → LTM (All Users)

• Thread-safe singleton: One instance per process, all operations safe for concurrency.

• Configurable: All limits, expirations, are adjustable.

• No vendor lock-in: Plug into any agent, LLM, or workflow.

• No required maintenance: Maintenance/cleanup is optional but recommended. Run in a background thread no lock-in or forced schedules.

• Bonus: Image storage and expiry: Store/expire/archive images and metadata if needed—totally optional.

---

Why HoloMem?

Most “memory” modules just log history or dump to a database. HoloMem is layered, time-aware, and models real-world cognition.

• Perception: Working context—ephemeral, in-memory, no disk. (Optional Use)
• Sensory: Fast, expiring, per-user buffer.
• STM: Recent active memory, rolls into LTM automatically.
• LTM: Archive—retrieve by date, user, or content.
• Image: Use if you need; never required.
• Memory Recall: Semantic (embedded/meaning-based) or Rapid (word-based) memory search. Both can be filtered by user or all users

You control all layouts, all workflows.

---

API Highlights

Perception (RAM only):

mem.savePerception("live context chunk")
mem.retrievePerception()   # FIFO, up to limit
mem.clearPerception()

Sensory / STM / LTM:

mem.saveSensory("input", "response", "user", mem.senDir)
mem.retrieveSensory(mem.getDir(mem.senDir, "user.db"))
mem.saveConversationDetails("input", "response", "user", mem.stmUserConversationDetails)
mem.retrieveConversationDetails("user", [mem.stmUserConversationDetails, mem.ltmUserConversationDetails])
mem.setSynMemModel("model_name") # Set the model for embeddings, if you forget to set it, it will default to rapid that way your memory recall is always available.
mem.recallMemory(
    "your query",
    [mem.stmUserConversationDetails, mem.ltmUserConversationDetails],
    user="user",         # or None for all users
    type="Embedded",     # or "Rapid"
    topK=5,              # number of results
    minScore=60,         # min score for Rapid
    showProgress=False
)

Bonus: Images (if needed):

mem.saveCreatedImage("subject", image_data, mem.stmCreatedImages, mem.stmCreatedImageDetails)

---

Maintenance (Optional, Recommended)

• Why? For auto-cleanup, auto-archival, and expired memory removal.
• Not required for operation.
• Enable any time—runs in the background so no blocking.

If you don’t enable maintenance, expired items will accumulate until you remove them.

---

Plug and Play

• No schemas, no boilerplate.
• Use with any LLM/agent plug-N-play and go.

---

FAQ

Q: Is perception persistent? A: No, it is always RAM-only.

Q: Do I need maintenance? A: No, but it’s strongly recommended for any long-running use.

Q: What if I don’t use image storage? A: Ignore all image APIs—they’re bonus, not core.

---

Code Examples

You can find code examples on my GitHub repository.

---

License

This project is licensed under the Apache License, Version 2.0. Copyright 2025 Tristan McBride Sr.

---

Acknowledgements

Project by:

• Tristan McBride Sr.
• Sybil