SKILL.md for agents

You can copy the following skill and paste it at .agents/skills/hippocampus/SKILL.md (you have to create it):

# hcamp Skill

Use this skill to interact with the Hippocampus local memory system via the `hcamp` CLI.

## Overview

Hippocampus is a local memory system that stores, retrieves, and summarizes structured memory events using embeddings and recency-aware ranking.

## Installation

```bash
cargo install hcamp
```

## Global Options

These flags apply to all commands:

* `--db-path <DB_PATH>`
  Path to the SQLite database (default: `hippocampus.db`)

* `--model-path <MODEL_PATH>`
  Path to ONNX embedding model (required for embedding-based features)

* `--embedding-dim <EMBEDDING_DIM>`
  Embedding vector size (default: 384)

* `--recency-half-life-secs <SECS>`
  Controls how quickly older memories decay in relevance (default: 86400)

## Commands

### write

Store a new memory entry.

```bash
hcamp write "memory text"
```

### search

Search stored memories using semantic similarity.

```bash
hcamp search "query text"
```


### recent

Show most recent memory entries.

```bash
hcamp recent
```

### tags

Filter or retrieve memories by tag (if supported internally).

```bash
hcamp tags <tag>
```


### reflect

Generate a synthesized summary over stored memories.

```bash
hcamp reflect "question or prompt"
```


### read

Read a specific memory by ID.

```bash
hcamp read <uuid>
```


## Behavior Notes

* Search ranking combines:

  * semantic similarity (embeddings)
  * recency decay (`recency-half-life-secs`)

* Older memories gradually lose ranking weight unless semantically strong.

* If the model is missing or incompatible, embedding-based features may fail.


## Output Format

* `write`: returns event ID + timestamp
* `search`: returns ranked list of matches
* `recent`: returns chronological list
* `reflect`: returns synthesized natural language summary
* `read`: returns raw stored memory


## Important Notes

* Ensure ONNX model is compatible with the embedding runtime.
* `tract-onnx` compatibility is required for model execution.
* Database is local and persistent unless `--db-path` is changed.