Sovereign Persistent Agentic Memory & Hierarchical Multi-Agent Task Substrate for AI coding assistants, autonomous agents, and developer terminal workflows.
MemoryZ acts as a shared, living cognitive substrate across Cursor, Claude Code, Windsurf, ChatGPT, and autonomous agent pipelines. It combines vector-based semantic retrieval with time-decay scoring, an isolated Zero-Knowledge vault for sensitive credentials, hierarchical task management, ephemeral scratchpad logs, and token-optimized context packing.
- Ultra-Compact Recall: Returns minimalist one-liners (
--compact) or summary bullet points (--summary), consuming ~15-25 tokens per item instead of 200+ tokens of bloated JSON. - Token-Budgeted Context Packs (
context_pack/memoryz context): Merges relevant memory atoms, active task trees, and environment rules into a single high-density prompt block with hard token budgeting (e.g. 1200 tokens).
- Parent-Child Subtask Nesting: Create epics, tasks, and nested subtasks at any depth.
- Open Flexible Statuses: Works with standard states (
todo,in_progress,done,blocked) or custom agent states without rigid lock-in. - Multi-Agent Handoff: One agent (e.g. Architect) drafts the task tree; another agent (e.g. Coder) claims a task (
in_progress), marks it completed (done), and updates status for downstream verification. - ASCII Tree Representation: Displays tasks as an ultra-compact visual hierarchy (
[✓] Task,[⏳] Subtask) that AI models understand with minimal token overhead.
- Zero-Embedding Overhead: High-speed appending of temporary logs, run traces, build outputs, and debugging scratchpads without consuming Gemini vector quota or cluttering long-term memory.
- Save and Restore Context: Agents can snapshot their active working memory or task progress before ending a turn and restore it later across conversations.
env: Ports, infrastructure flags, local domains, process managers.preference: Developer coding styles, conventions, architectural patterns.skill: Multi-step agent workflows, procedures, and prompt directives.note: Reference snippets, architectural notes, and documentation pointers.
- Supports
parent_idrecursive nesting,status,priority,assignee, and auto-timestamps (completed_at).
- Isolated
vault_entriesstorage. - Never indexed by vector embeddings.
- Client-side AES-256-GCM encryption with PBKDF2 key derivation (100,000 rounds).
- Secrets decrypted strictly in process memory.
memory_linkstable supports typed semantic graphs:depends_on,context_for,related, andsupersedes.
npx memoryz init --token=<YOUR_API_KEY>This command:
- Validates connection to the MemoryZ Substrate.
- Auto-registers the MCP server in
~/.cursor/mcp.json, Claude Desktop, Claude Code (~/.claude/mcp.json), and Windsurf (~/.codeium/windsurf/mcp_config.json). - Saves credentials locally in
~/.memoryz/config.json. - Generates
.agents/skills/memoryz/SKILL.md,CLAUDE.md, andAGENTS.md.
# View task tree (token-efficient ASCII hierarchy)
memoryz task list --tree
# Filter active or pending tasks
memoryz task list --status=active
# Create a root task
memoryz task add "Refactor Authentication Module" --priority=high --assignee=architect
# Create a nested subtask under a parent task
memoryz task add "Implement JWT verification" --parent=task_xxx --assignee=coder
# Mark a task done
memoryz task done task_xxx
# Update task status or details
memoryz task update task_xxx --status=in_progress --assignee=claude
# Delete a task and its descendants
memoryz task rm task_xxx# Token-efficient compact recall (saves tokens)
memoryz recall "database ports" --compact
# Standard semantic vector recall
memoryz recall "database ports" --limit=3
# Store new memory atom (with automatic 768-dim Gemini embedding)
memoryz store --type=preference --content="Always use TypeScript strict mode"
# Store via pipe
echo "Staging runs on port 4000" | memoryz store --type=env --title="staging_port"# Log a quick trace or status
memoryz log "Database migration completed in 42ms" --level=info --source=deploy
# View recent ephemeral logs
memoryz logs --limit=20# Generate dense, token-budgeted prompt context block (active tasks + memories)
memoryz context "Authentication" --tokens=1200 --compact
# Save a working memory snapshot
memoryz snapshot save "auth-refactor-session" "Working on JWT routes. Next: unit tests."
# Restore context snapshot
memoryz snapshot get "auth-refactor-session"# Encrypt secret in vault
memoryz vault store --key="stripe_key" --secret="sk_live_..." --pass="passphrase"
# Decrypt secret
memoryz vault get --key="stripe_key" --pass="passphrase"
# List vault handles
memoryz vault list# Run standard MCP JSON-RPC protocol over stdio
memoryz mcp| Tool | Parameters | Description |
|---|---|---|
task_create |
title, parent_id, status, priority, assignee, description |
Create hierarchical task or child subtask |
task_list |
status, parent_id, format (tree, compact, json) |
List tasks in token-saving ASCII tree or list |
task_update |
id, status, title, priority, assignee, parent_id |
Update task status (e.g. done), details, or assignment |
task_delete |
id, cascade |
Delete task and optionally its descendants |
recall_memory |
query, type, limit, format (compact, summary, full) |
Semantic vector search with token-saving formats |
store_memory |
type, content, title, metadata |
Persist memory atom with Gemini embedding |
link_memory |
source_hash, target_hash, relation_type |
Connect memories in the knowledge graph |
log_store |
message, level, source, metadata |
Append ephemeral log without embedding overhead |
log_list |
limit, level, source, format |
Retrieve recent ephemeral logs |
context_pack |
query, token_budget, include_tasks, include_logs, format |
Pack token-budgeted prompt context (tasks + memories) |
context_snapshot_save |
name, content, description |
Save full context checkpoint |
context_snapshot_load |
name |
Restore context checkpoint |
vault_store |
key_name, secret_value, passphrase |
Encrypt and store secret in Zero-Knowledge vault |
vault_retrieve |
key_name, passphrase |
Decrypt secret in transient RAM |
vault_list |
(none) | List stored vault key metadata |
import {
recall,
store,
taskCreate,
taskList,
taskDone,
logStore,
getContextPack
} from "memoryz";
// 1. Hierarchical tasks
const parent = await taskCreate({ title: "Build Auth Module", priority: "high" });
const subtask = await taskCreate({ title: "Add JWT middleware", parentId: parent.id, assignee: "agent_1" });
await taskDone(subtask.id);
// 2. Token-budgeted context pack
const promptContext = await getContextPack("auth module", { tokens: 1000 });
// 3. Ephemeral logs
await logStore({ message: "Auth test passed", level: "info" });- Deno 2.0+
- Turso Cloud database (
libSQL) - Gemini API key
git clone https://github.com/Zizwar/memoryz.git
cd memoryz
cp .env.example .env
deno task devMIT