https://github.com/bubustack/conversation-memory-engram
Per-session conversation memory Engram for bobrapet — bounded history with TTL eviction, dedup, and context packet emission.
https://github.com/bubustack/conversation-memory-engram
batch bubustack context conversation engram go kubernetes memory streaming
Last synced: 11 days ago
JSON representation
Per-session conversation memory Engram for bobrapet — bounded history with TTL eviction, dedup, and context packet emission.
- Host: GitHub
- URL: https://github.com/bubustack/conversation-memory-engram
- Owner: bubustack
- License: apache-2.0
- Created: 2026-04-12T15:54:08.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-04-18T10:01:57.000Z (11 days ago)
- Last Synced: 2026-04-18T10:11:57.800Z (11 days ago)
- Topics: batch, bubustack, context, conversation, engram, go, kubernetes, memory, streaming
- Language: Go
- Homepage: https://bubustack.io/
- Size: 46.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# 🧠 Conversation Memory Engram
Keeps a bounded per-session conversation history and emits `conversation.context.v1`
packets for downstream prompts without requiring each Engram to implement its own
memory layer.
## 🌟 Highlights
- Maintains per-key message history with TTL-based eviction and optional deduplication.
- Supports both batch Jobs and streaming Deployments under the same Engram spec.
- Produces normalized context packets downstream Engrams can consume immediately.
- Offers configurable merge windows, rate-limited sweeps, and flexible role mapping.
## 🚀 Quick Start
```bash
go vet ./...
go test ./...
docker build -t ghcr.io/bubustack/conversation-memory-engram:dev .
```
Deploy the resulting container as part of a bobrapet Story. Use the sample
`Engram.yaml` to register the template and pick defaults for your project.
## ⚙️ Configuration (`Engram.spec.with`)
| Field | Default | Description |
| --- | --- | --- |
| `maxMessages` | `16` | Maximum history length stored per key. |
| `sessionTTL` | `45m` | Idle TTL before conversation keys are swept. |
| `sweepInterval` | `1m` | How often the engram reaps expired keys. |
| `minUserChars` | `4` | Minimum user text length that contributes to history. |
| `ignorePattern` | `(?i)^(mhm+|hmm+|uh+|um+|ok(?:ay)?|mm+|huh)[.!? ]*$` | Regex of filler utterances to ignore for `role=user`. |
| `dedupeWindow` | `1500ms` | Suppresses duplicate role-text pairs within this window. |
| `mergeWindowMs` | `3000` | Merges consecutive same-role packets arriving within this window. |
| `defaultRole` | `user` | Role used when metadata omits a role. |
## 📥 Inputs
| Field | Description |
| --- | --- |
| `key` | Explicit conversation key. If omitted, the engram derives one from session or participant metadata. |
| `sessionId` | Optional session identifier used when deriving the conversation key. |
| `role` | `user`, `assistant`, `developer`, or `system` (defaults to `defaultRole`). |
| `text` / `assistantText` | Message content to add to history. |
| `speakerId` | Optional identifier used for deduplication and merge logic. |
| `reset` | Boolean flag to drop existing history for the current key before processing the message. |
| `maxMessages` | Per-request override for the retained history length. |
| `minUserChars` | Per-request override for the minimum accepted user transcript length. |
| `includeHistory` | When `false`, suppresses the `history` array in the emitted context packet. |
Additional passthrough fields such as `metadata` are preserved for downstream context assembly because the input schema allows extra properties.
## 📤 Outputs
Emits a `conversation.context.v1` payload containing:
- `accepted`: boolean indicating the message was accepted into history.
- `role`, `text`, `speakerId`, and timestamps from the last stored message.
- `history`: trimmed list of prior messages (bounded by `maxMessages`).
- `metadata`: merged metadata from the stored history and the latest packet.
- `diagnostics`: when `BUBU_DEBUG=true`, exposes TTL and sweep metadata.
## 🧪 Local Development
- `go vet ./...` – Runs Go vet checks.
- `go test ./...` – Unit tests covering merging, dedup, and hydration.
- `docker build -t ghcr.io/bubustack/conversation-memory-engram:dev .` – Builds the container image.
## 🤝 Community & Support
- [Contributing](./CONTRIBUTING.md)
- [Support](./SUPPORT.md)
- [Security Policy](./SECURITY.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Discord](https://discord.gg/dysrB7D8H6)
## 📄 License
Copyright 2025 BubuStack.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.