CLI
cargo install pensyve-cli
# or
cargo run -p pensyve-cli -- <command>pensyve 0.1.0
Universal memory runtime for AI agents
USAGE:
pensyve <COMMAND>
COMMANDS:
recall Recall memories matching a query
stats Show memory statistics for a namespace
inspect Inspect memories for a specific entitypensyve recall
Search memories matching a query. Output is a JSON array of scored results.
pensyve recall <QUERY> [OPTIONS]Arguments:
| Argument | Type | Required | Description |
|---|---|---|---|
QUERY | string | yes | Search query |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--entity | string | none | Filter by entity name |
--limit | integer | 5 | Max results |
--namespace | string | "default" | Namespace to search |
Output: JSON array of memory objects with score breakdowns.
pensyve recall "deployment process"[
{
"id": "a1b2c3d4-...",
"type": "procedural",
"content": "deploy -> run CI pipeline then push to production",
"score": 0.82,
"vector_score": 0.75,
"bm25_score": 0.90,
"recency_score": 0.65,
"confidence_score": 0.95
}
]Filter by entity:
pensyve recall "preferences" --entity alice --limit 10Search a specific namespace:
pensyve recall "API keys" --namespace project-xpensyve stats
Show memory statistics for a namespace. Output is a JSON object.
pensyve stats [OPTIONS]Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace | string | "default" | Namespace to show stats for |
pensyve stats{
"namespace": "default",
"storage_path": "/Users/alice/.pensyve/default",
"counts": {
"episodic": 42,
"semantic": 15,
"procedural": 3,
"total": 60
},
"storage_bytes": 524288
}pensyve stats --namespace project-xpensyve inspect
Inspect memories for a specific entity. Output is a JSON object with the entity info and an array of memories.
pensyve inspect [OPTIONS]Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--entity | string | required | Entity name to inspect |
--type | string | none | Filter: "episodic", "semantic", or "procedural" |
--namespace | string | "default" | Namespace to search |
pensyve inspect --entity alice{
"entity": {
"id": "550e8400-...",
"name": "alice",
"kind": "User"
},
"namespace": "default",
"memories": [
{
"id": "...",
"type": "episodic",
"content": "Asked about project X deadline",
"timestamp": "2026-03-19T12:00:00Z",
"stability": 0.95,
"retrievability": 0.88,
"access_count": 3
},
{
"id": "...",
"type": "semantic",
"predicate": "prefers",
"object": "dark mode",
"confidence": 0.9,
"valid_at": "2026-03-18T10:00:00Z",
"invalid_at": null
}
]
}Filter to a specific memory type:
pensyve inspect --entity alice --type semanticIf the entity is not found:
{
"entity": "alice",
"namespace": "default",
"error": "entity not found",
"memories": []
}Storage
By default, the CLI stores data in ~/.pensyve/<namespace>/. Each namespace gets its own SQLite database at memories.db inside that directory.
Override with PENSYVE_PATH:
PENSYVE_PATH=/tmp/mydata pensyve stats