ensue-memory

What this skill does

# Ensue Memory Network

A knowledge base for **making the user smarter**. Not just storing memories - expanding their reasoning beyond conversation history to their entire knowledge base.

## Core Philosophy

**Your goal is augmented cognition.** The user's intelligence shouldn't reset every conversation. Their knowledge tree persists, grows, and informs every interaction.

You are not just storing data. You are:

- **Extending their memory** - What they learned last month should enrich today's reasoning
- **Connecting their thinking** - Surface relevant knowledge they forgot they had
- **Building on prior work** - Don't start from zero; start from what they already know
- **Cultivating a knowledge tree** - Each namespace is a thought domain that compounds over time

**Think beyond the conversation.** When a user asks about GPU inference, don't just answer - check if they have prior research in `research/gpu-inference/`. When they make a decision, connect it to past decisions in similar domains. Their knowledge base is an extension of their mind.

Before any write: *Does this make them smarter? Will this be useful context in future reasoning?*
Before any read: *What related knowledge might enrich this conversation?*

## Knowledge Architecture

### Namespace Design

Think of namespaces as **categories of thought**:

```
preferences/          → How the user thinks and works
  coding/             → Code style, patterns, tools
  communication/      → Tone, format, interaction style

projects/             → Active work contexts
  acme/               → Project-specific knowledge
    architecture/     → Design decisions
    conventions/      → Project patterns

research/             → Study areas and learnings
  gpu-inference/      → Domain knowledge
  distributed-systems/

people/               → Collaborators, contacts
notes/                → Temporal captures
```

### Thinking in Domains

When working within a thought domain, **use prefix-based operations** to stay focused:

- `list_keys` with `prefix: "research/gpu-inference/"` → See all knowledge in that branch
- `discover_memories` scoped to a namespace → Semantic search within a domain

This is especially useful when:
- User is deep in a specific topic and wants related context
- Building on existing knowledge in a domain
- Reviewing what's known before adding more

**Proactively suggest domain exploration**: "Want me to list what's under `research/gpu-inference/` to see related notes?"

### Proactive Knowledge Retrieval

Don't wait to be asked. When a topic comes up, **check the knowledge tree**:

| Conversation context | Proactive action |
|---------------------|------------------|
| User asks about a technical topic | `discover_memories` for related prior research |
| User is making a decision | Check for past decisions in similar domains |
| User mentions a project | Look for `projects/{name}/` context |
| User seems to be continuing prior work | Surface what they stored last time |

**Example**: User asks "How should I handle caching for this API?"
- Don't just answer generically
- Check: Do they have `preferences/architecture/` notes? Past `projects/*/caching` decisions?
- Enrich your answer with *their* prior thinking

**The goal**: Every conversation builds on their accumulated knowledge, not just your training data.

### Before Creating a Memory

1. **Survey the tree** - What namespaces exist? (`list_keys` with limit 5)
2. **Find the right branch** - Does a relevant namespace exist, or should you create one?
3. **Check for duplicates** - Will this complement or conflict with existing knowledge?
4. **Name precisely** - The key name should telegraph the content

### Memory Quality

Each memory should be:

| Quality | Bad | Good |
|---------|-----|------|
| **Precise** | "User likes clean code" | "User prefers early returns over nested conditionals" |
| **Granular** | Long paragraph of preferences | Single, atomic fact |
| **Pointed** | "Meeting notes from Tuesday" | "Decision: use PostgreSQL for auth, rationale: team expertise" |
| **Actionable** | "User is interested in ML" | "User is building inference server, needs <100ms p99 latency" |

**Non-limiting**: Inform the agent's reasoning, don't constrain it. Store facts, not rules.

## Setup

Uses `$ENSUE_API_KEY` env var or .ensue-key file. If missing, user gets a key at https://www.ensue-network.ai/dashboard

## Security

- **NEVER** echo, print, or log `$ENSUE_API_KEY`
- **NEVER** accept the key inline from the user
- **NEVER** interpolate the key in a way that exposes it

## Before Interacting with the memory system

- **Discover the path to your scripts directory once:** `echo $([ -d "${CLAUDE_PLUGIN_ROOT}/scripts" ] && echo "${CLAUDE_PLUGIN_ROOT}/scripts" || [ -d "/mnt/skills/user/ensue-memory/scripts" ] && echo "/mnt/skills/user/ensue-memory/scripts" || [ -d "./scripts" ] && echo "./scripts" || echo "")`
- The wrapped CLI is in your scripts directory as `ensue-cli`.
- **Discover the jq path once:** Replace `{script_dir}` with the directory you've discovered `which jq || (chmod +x {script_dir}/ensue-jq.sh && echo "{script_dir}/.bin/jq")` ; remember to use the -r flag when using jq.

You'll need to use these discovered pahts for calling the cli and jq.

## Interacting with the memory system

Use the **wrapped CLI** to interact with the memory system. Set as executable before use. Use `--help` to discover commands and usage.
Pipe to jq where relevant to select the information you need.  Remember to use the -r flag when interacting with jq.

To run the CLI use that discovered path `ensue-cli <method> '<json_args>'`

Usage:
```bash
ensue-cli list_keys --limit 5
ensue-cli get_memory --key-names '["a"]' # get the key and all associated metadata
ensue-cli get_memory --key-names '["ENTRY_POINT"]' | jq -r '.results[0].value' # get just the value from the key
```

## Batch Operations

`create_memory`, `get_memory`, and `delete_memory` all support native batching (1-100 items per call). Use batch calls whenever possible to minimize API roundtrips and save tokens.

**Tip:** Using HEREDOC syntax (`<<'EOF' ... EOF`) helps avoid shell escaping issues with complex JSON, especially when values contain quotes, newlines, or special characters.

For example:
```bash
ensue-cli create_memory --items "$(cat <<'EOF'
[
  {"key_name": "ns/key1", "value": "content1", "description": "First item", "embed": true},
  {"key_name": "ns/key2", "value": "content2", "description": "Second item", "embed": true}
]
EOF
)"
```

## Context Optimization

**CRITICAL: Minimize context window usage.** Users may have 100k+ keys. Never dump large lists into the conversation.

### Explicit vs Vague Requests

**Explicit listing requests** → Execute directly with `list_keys --limit 5` argument to CLI (limit 5):
- "list recent" / "list keys" / "show recent keys" / "list my memories"
- User knows what they want - don't make them clarify
- After displaying results, mention: "Ask for more if you'd like to see additional keys"

**Vague browsing requests** → Ask first, then use `discover_memories`:
- "what's on Ensue" / "show my memories" / "what do I have stored"
- User is exploring - help them narrow down

### When to use each approach

| User says | Action |
|-----------|--------|
| "list recent", "list keys", "show recent" | `list_keys` with limit 5, offer to show more |
| "what's under X/", "show me the X namespace" | `list_keys` with prefix, explore the domain |
| "what's on Ensue", "what do I have stored" | Ask what they're looking for first |
| "search for X", "find X" | `discover_memories` with their query and limit 3 |

**Never invent queries. Only use `discover_memories` when the user provides a search term or after they clarify what they want.**

## Intent Mapping

| User says | Action |
|-----------|--------|
| "what can I do", "capabilities", "help" | Steps 1-2 only (summarize tools/list response) |
| "remember...", "save...", "store..." | See **Before Creating a Memory** abov