---
# SynMem – 4-Stage Synthetic Memory
## Overview
**SynMem** 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 SynMem?
Most “memory” modules just log history or dump to a database.
**SynMem** 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):**
```python
mem.savePerception("live context chunk")
mem.retrievePerception() # FIFO, up to limit
mem.clearPerception()
```
**Sensory / STM / LTM:**
```python
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):**
```python
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](https://github.com/TristanMcBrideSr/TechBook).
---
## License
This project is licensed under the [Apache License, Version 2.0](LICENSE).
Copyright 2025 Tristan McBride Sr.
---
## Acknowledgements
Project by:
- Tristan McBride Sr.
- Sybil
Raw data
{
"_id": null,
"home_page": null,
"name": "SynMem",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "\"Tristan McBride Sr.\" <142635792+TristanMcBrideSr@users.noreply.github.com>",
"keywords": "AI, Agents, Memory, Productivity, Automation, Voice Assistant, Chatbot, LLM, Large Language Model",
"author": "Tristan McBride Sr.",
"author_email": "\"Tristan McBride Sr.\" <142635792+TristanMcBrideSr@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/87/5c/f5373f8deef89dc7b14767f4c2a52df66e09e3e20c0c9eeecdbaffc34156/synmem-0.1.6.tar.gz",
"platform": null,
"description": "\ufeff\r\n---\r\n\r\n# SynMem \u2013 4-Stage Synthetic Memory\r\n\r\n## Overview\r\n\r\n**SynMem** is a production-grade, multi-stage synthetic memory framework inspired by real cognition.\r\n**Built for AI Agents, LLMs, Voice Assistants and more with advanced automation**.\r\n\r\n**Stages:**\r\n\r\n1. **Perception** \u2013 Immediate, in-memory (RAM) context \r\n - *Optional, not required*\r\n2. **Sensory** \u2013 Short-lived, per-user episodic memory\r\n3. **STM (Short-Term Memory)** \u2013 Active conversation/session memory\r\n4. **LTM (Long-Term Memory)** \u2013 Persistent archive\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n* **Direct, 4-stage architecture:**\r\n\r\n * *Perception* (RAM) *Sensory* (Per User) \u2192 *STM* (All Users) \u2192 *LTM* (All Users)\r\n* **Thread-safe singleton:**\r\n One instance per process, all operations safe for concurrency.\r\n* **Configurable:**\r\n All limits, expirations, are adjustable.\r\n* **No vendor lock-in:**\r\n Plug into any agent, LLM, or workflow.\r\n* **No required maintenance:**\r\n **Maintenance/cleanup is optional but recommended.**\r\n Run in a background thread no lock-in or forced schedules.\r\n* **Bonus: Image storage and expiry:**\r\n Store/expire/archive images and metadata if needed\u2014totally optional.\r\n\r\n---\r\n\r\n## Why SynMem?\r\n\r\nMost \u201cmemory\u201d modules just log history or dump to a database.\r\n**SynMem** is layered, time-aware, and models real-world cognition.\r\n\r\n* **Perception**: Working context\u2014ephemeral, in-memory, no disk. (Optional Use)\r\n* **Sensory**: Fast, expiring, per-user buffer.\r\n* **STM**: Recent active memory, rolls into LTM automatically.\r\n* **LTM**: Archive\u2014retrieve by date, user, or content.\r\n* **Image**: Use if you need; never required.\r\n* **Memory Recall:**\r\n Semantic (embedded/meaning-based) or Rapid (word-based) memory search.\r\n Both can be filtered by user or all users\r\n\r\nYou control all layouts, all workflows.\r\n\r\n---\r\n\r\n## API Highlights\r\n\r\n**Perception (RAM only):**\r\n\r\n```python\r\nmem.savePerception(\"live context chunk\")\r\nmem.retrievePerception() # FIFO, up to limit\r\nmem.clearPerception()\r\n```\r\n\r\n**Sensory / STM / LTM:**\r\n\r\n```python\r\nmem.saveSensory(\"input\", \"response\", \"user\", mem.senDir)\r\nmem.retrieveSensory(mem.getDir(mem.senDir, \"user.db\"))\r\nmem.saveConversationDetails(\"input\", \"response\", \"user\", mem.stmUserConversationDetails)\r\nmem.retrieveConversationDetails(\"user\", [mem.stmUserConversationDetails, mem.ltmUserConversationDetails])\r\nmem.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.\r\nmem.recallMemory(\r\n \"your query\",\r\n [mem.stmUserConversationDetails, mem.ltmUserConversationDetails],\r\n user=\"user\", # or None for all users\r\n type=\"Embedded\", # or \"Rapid\"\r\n topK=5, # number of results\r\n minScore=60, # min score for Rapid\r\n showProgress=False\r\n)\r\n```\r\n\r\n**Bonus: Images (if needed):**\r\n\r\n```python\r\nmem.saveCreatedImage(\"subject\", image_data, mem.stmCreatedImages, mem.stmCreatedImageDetails)\r\n```\r\n\r\n---\r\n\r\n## Maintenance (Optional, Recommended)\r\n\r\n* **Why?**\r\n For auto-cleanup, auto-archival, and expired memory removal.\r\n* **Not required for operation.**\r\n* **Enable any time**\u2014runs in the background so no blocking.\r\n\r\n**If you don\u2019t enable maintenance, expired items will accumulate until you remove them.**\r\n\r\n---\r\n\r\n## Plug and Play\r\n\r\n* No schemas, no boilerplate.\r\n* Use with any LLM/agent plug-N-play and go.\r\n\r\n---\r\n\r\n## FAQ\r\n\r\n**Q: Is perception persistent?**\r\nA: No, it is always RAM-only.\r\n\r\n**Q: Do I need maintenance?**\r\nA: No, but it\u2019s strongly recommended for any long-running use.\r\n\r\n**Q: What if I don\u2019t use image storage?**\r\nA: Ignore all image APIs\u2014they\u2019re bonus, not core.\r\n\r\n---\r\n\r\n## Code Examples\r\n\r\nYou can find code examples on my [GitHub repository](https://github.com/TristanMcBrideSr/TechBook).\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the [Apache License, Version 2.0](LICENSE).\r\nCopyright 2025 Tristan McBride Sr.\r\n\r\n---\r\n\r\n## Acknowledgements\r\n\r\nProject by:\r\n- Tristan McBride Sr.\r\n- Sybil\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Modern 4-Stage Synthetic Memory",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/TristanMcBrideSr"
},
"split_keywords": [
"ai",
" agents",
" memory",
" productivity",
" automation",
" voice assistant",
" chatbot",
" llm",
" large language model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02cfcadebb41b28f6508584c92b0cdb8e50f3a16800f33723a6d13ad7ed44634",
"md5": "2f1975d41eaadb70fecd0704fcfe0bd4",
"sha256": "2b81ca98bb4845e88bd9acb4f37c366092bb43e820bfdd280af0edf59f69c4fb"
},
"downloads": -1,
"filename": "synmem-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f1975d41eaadb70fecd0704fcfe0bd4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19507,
"upload_time": "2025-07-17T21:19:38",
"upload_time_iso_8601": "2025-07-17T21:19:38.709393Z",
"url": "https://files.pythonhosted.org/packages/02/cf/cadebb41b28f6508584c92b0cdb8e50f3a16800f33723a6d13ad7ed44634/synmem-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "875cf5373f8deef89dc7b14767f4c2a52df66e09e3e20c0c9eeecdbaffc34156",
"md5": "ba723bc2e4c0efc8ea9ad6d42c4329ab",
"sha256": "9efc887af2a36079b3237811b79d2cc52c649c22258fb33de47cb5d515dd0bc3"
},
"downloads": -1,
"filename": "synmem-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "ba723bc2e4c0efc8ea9ad6d42c4329ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17524,
"upload_time": "2025-07-17T21:19:39",
"upload_time_iso_8601": "2025-07-17T21:19:39.781343Z",
"url": "https://files.pythonhosted.org/packages/87/5c/f5373f8deef89dc7b14767f4c2a52df66e09e3e20c0c9eeecdbaffc34156/synmem-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 21:19:39",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "synmem"
}
JSON