Vanar Neutron Memory

# Vanar Neutron Memory

Persistent memory storage with semantic search for AI agents. Save text as seeds, search semantically, and persist agent context between sessions.

## Features

- **Auto-Recall**: Automatically queries relevant memories before each AI turn and injects as context - **Auto-Capture**: Automatically saves conversations after each AI turn - **Semantic Search**: Find memories by meaning using Jina Embeddings v4 (1024 dimensions) - **Memory Types**: Episodic, semantic, procedural, and working memory - **Blockchain Attestation**: Tamper-evident memory storage with transaction hashes

## Prerequisites

Get your API keys at: **https://openclaw.vanarchain.com/**

API credentials via environment variables: ```bash export NEUTRON_API_KEY=your_key export NEUTRON_AGENT_ID=your_agent_id export YOUR_AGENT_IDENTIFIER=your_agent_name_or_id # agent_id name or defaults to 1 ```

Or stored in `~/.config/neutron/credentials.json`: ```json { "api_key": "your_key_here", "agent_id": "your_agent_id_here", "your_agent_identifier": "your_agent_name_or_id" } ```

## Testing

Verify your setup: ```bash ./scripts/neutron-memory.sh test # Test API connection ```

## Hooks (Auto-Capture & Auto-Recall)

The skill includes OpenClaw hooks for automatic memory management:

- `hooks/pre-tool-use.sh` - **Auto-Recall**: Queries memories before AI turn, injects relevant context - `hooks/post-tool-use.sh` - **Auto-Capture**: Saves conversation after AI turn

### Configuration

Both features are **enabled by default**. To disable:

```bash export VANAR_AUTO_RECALL=false # Disable auto-recall export VANAR_AUTO_CAPTURE=false # Disable auto-capture ```

Or add to your credentials file: ```json { "api_key": "your_key_here", "agent_id": "your_agent_id_here", "your_agent_identifier": "your_agent_name_or_id", "auto_recall": true, "auto_capture": true } ```

## Scripts

Use the provided bash script in the `scripts/` directory: - `neutron-memory.sh` - Main CLI tool

## Common Operations

### Save Text as a Seed ```bash ./scripts/neutron-memory.sh save "Content to remember" "Title of this memory" ```

### Semantic Search ```bash ./scripts/neutron-memory.sh search "what do I know about blockchain" 10 0.5 ```

### Create Agent Context ```bash ./scripts/neutron-memory.sh context-create "my-agent" "episodic" '{"key":"value"}' ```

### List Agent Contexts ```bash ./scripts/neutron-memory.sh context-list "my-agent" ```

### Get Specific Context ```bash ./scripts/neutron-memory.sh context-get abc-123 ```

## Interaction Seeds (Dual Storage)

When NeutronMemoryBot processes an interaction, it stores data in two places:

1. **Agent Context** - Truncated summary for structured metadata and session tracking 2. **Seed** - Full thread snapshot for semantic search

Each time the bot replies to a comment, the **full thread** (original post + all comments + the bot's reply) is saved as a seed. This means:

- Every seed is a complete conversation snapshot - Later seeds contain more context than earlier ones - Semantic search finds the most relevant conversation state - Append-only: new snapshots are added, old ones remain

### Seed Format

``` Thread snapshot - {timestamp}

Post: {full post content}

Comments: {author1}: {comment text} {author2}: {comment text} NeutronMemoryBot: {reply text} ```

## API Endpoints

- `POST /seeds` - Save text content (multipart/form-data) - `POST /seeds/query` - Semantic search (JSON body) - `POST /agent-contexts` - Create agent context - `GET /agent-contexts` - List contexts (optional `agentId` filter) - `GET /agent-contexts/{id}` - Get specific context

**Auth:** All requests require `Authorization: Bearer $NEUTRON_API_KEY` header and `appId`/`externalUserId` query params.

**Memory types:** `episodic`, `semantic`, `procedural`, `working`

**Text types for seeds:** `text`, `markdown`, `json`, `csv`, `claude_chat`, `gpt_chat`, `email`