Greeum
Persistent memory for AI agents — no more context loss between sessions.
Greeum is an open-source memory module that gives LLM agents long-term memory. Store memories on your own workstation, access them from anywhere, and never lose context again.
Quick Start
# Install
pip install greeum
# Setup (interactive wizard)
greeum setup
# Test
greeum memory add "My first memory"
greeum memory search "first"
That's it. Greeum is ready to use with your MCP client.
Setup Modes
greeum setup provides three modes depending on your use case:
Local (default)
Store memories on this computer only.
greeum setup
# Select [1] Local
Server
Turn this computer into a Greeum server accessible from anywhere. Handles API key generation, Tailscale networking, and auto-start on boot.
greeum setup --server
[1/5] Data directory ~/.greeum ✓
[2/5] Embedding model ready ✓
[3/5] API server port 8400, key generated ✓
[4/5] Tailscale network connected ✓
[5/5] System service auto-start enabled ✓
Remote
Connect to an existing Greeum server — one command.
greeum setup --remote http://my-server:8400 --api-key grm_xxxxx
All MCP tools and CLI commands will use the remote server automatically.
MCP Integration
Once greeum setup is complete, connect your MCP client:
Claude Code
claude mcp add greeum -- greeum mcp serve -t stdio
Cursor
Add to MCP settings:
{
"greeum": {
"command": "greeum",
"args": ["mcp", "serve", "-t", "stdio"]
}
}
Codex
~/.codex/config.toml:
[mcp_servers.greeum]
command = "greeum"
args = ["mcp", "serve", "-t", "stdio"]
Greeum MCP is supported on Linux, macOS, and WSL. On Windows, use WSL.
MCP Tools
Greeum provides these tools to your AI agent via MCP:
| Tool | Description |
|---|---|
add_memory |
Store a memory with optional importance score |
search_memory |
Semantic search across all memories |
get_memory_stats |
View memory count, slots, and system health |
usage_analytics |
Analyze usage patterns over time |
system_doctor |
Run diagnostics and auto-repair |
analyze |
Summarize recent activity and slot status |
How agents use Greeum
- Search before starting work — retrieve relevant context
- Work on the task with full context
- Add a summary when done — preserve decisions and outcomes
{ "name": "search_memory", "arguments": { "query": "auth refactor", "limit": 5 } }
{ "name": "add_memory", "arguments": { "content": "Switched to JWT tokens for auth", "importance": 0.7 } }
CLI Reference
# Memory operations
greeum memory add "context to remember"
greeum memory add "important note" --importance 0.8
greeum memory search "keyword" --count 5
# Slot management
greeum slots status
greeum slots set A 123 # Pin memory #123 to slot A
# Server management
greeum config show # View current configuration
greeum config mode local # Switch to local mode
greeum config mode remote # Switch to remote mode
greeum config test # Test remote connection
# Maintenance
greeum doctor # System diagnostics
greeum mcp warmup # Pre-download embedding model
Architecture
┌─────────────────────────────────────────────┐
│ Your Workstation │
│ │
│ greeum api serve (:8400) │
│ ├── Semantic Search (sentence-transformers)│
│ ├── STM Slots (A/B/C context anchors) │
│ ├── Branch-aware LTM storage (SQLite) │
│ └── API Key authentication │
│ │
│ Accessible via Tailscale from anywhere │
└─────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
Claude Code Cursor Codex
(MCP/STDIO) (MCP/STDIO) (MCP/STDIO)
Documentation
License
MIT License — see LICENSE.
Greeum · Persistent memory for AI — built and maintained by the community.
1 maintainer
Metadata
1 maintainer
Release files for greeum 5.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| greeum-5.3.0.tar.gz | 499.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| greeum-5.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / greeum-5.3.0.tar.gz
| Download URL | greeum-5.3.0.tar.gz |
|---|---|
| Size | 499.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ae6f792454314177a2af0ea8b1ad037f6dfcd9390214c6e0fd8b425cb1bc7cb
|
|
BLAKE2b-256 checksum How to use checksums |
bcb63be7caaa57647d3925673317b710a96b178b7db9a0e76f3a2e049b7112c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Release files / greeum-5.3.0-py3-none-any.whl
| Download URL | greeum-5.3.0-py3-none-any.whl |
|---|---|
| Size | 547.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
627f400c1b38f6c75e7bb23ae50833dc41438014a3b82c40f184b426e86f4651
|
|
BLAKE2b-256 checksum How to use checksums |
77f0fb5d53151c520188a2e729b5f91e2d1544f8ed83181fc168e75e02e09098
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Security for greeum 5.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
