penrose-memory 1.1.0

Aperiodic memory palace for AI agents with tile lifecycle, simulation-first predictions, and Lamport clocks.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

Metadata-Version: 2.4
Name: penrose-memory
Version: 0.1.0
Summary: Aperiodic memory palace for AI agents. Navigate memories by distance + direction.
License: MIT
Project-URL: Repository, https://github.com/SuperInstance/penrose-memory
Keywords: penrose,memory,ai,tiling,aperiodic
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Penrose Memory

Aperiodic memory palace for AI agents. Navigate memories by **distance + direction** on a Penrose floor.

## How It Works

1. **Project**: Embeddings → 2D Penrose coordinates via golden-ratio hashing
2. **Store**: Place memories on the floor at projected coordinates
3. **Recall**: Dead-reckon from query toward stored memories
4. **Navigate**: Walk from any tile by distance + heading
5. **Consolidate**: Merge nearby memories using golden hierarchy (φ^k)

The Fibonacci word determines tile bits (thick:thin → 1/φ). Matching rules verify valid positions. 3-coloring enables sharding.

## Install

```toml
[dependencies]
penrose-memory = "1.0.0"
```

Python:
```bash
pip install penrose-memory
```

## Quick Start (Rust)

```rust
use penrose_memory::PenroseMemory;

let mut pm = PenroseMemory::new(1536);

// Store an embedding with content
let id = pm.store(&embedding, 42);

// Recall by nearest embedding
let results = pm.recall(&query, 5);
for r in &results {
    println!("id={} conf={:.3} dist={:.3}", r.tile_id, r.confidence, r.distance);
}

// Navigate from a tile
let nearby = pm.navigate(id, 2.5, std::f64::consts::FRAC_PI_4);

// Consolidate old memories
pm.consolidate();
```

## Quick Start (Python)

```python
from penrose_memory import PenroseMemory

pm = PenroseMemory(embedding_dim=1536)

# Store text with embedding
tile_id = pm.store("hello world", embedding)

# Recall by query embedding
results = pm.recall(query_embedding, max_steps=5)
for r in results:
    print(r["text"], r["confidence"], r["distance"])

# Navigate from a tile
nearby = pm.navigate(tile_id, distance=2.5, heading=0.785)

# Consolidate
removed = pm.consolidate()
```

## API

### Rust

| Method | Description |
|--------|-------------|
| `new(dim)` | Create with embedding dimension |
| `store(&[f64], u64) -> u64` | Store embedding + content, returns tile_id |
| `recall(&[f64], steps) -> Vec<RecallResult>` | Recall by dead reckoning |
| `navigate(id, dist, heading) -> Vec<u64>` | Navigate from tile |
| `consolidate()` | Merge nearby memories |
| `len() -> usize` | Memory count |

### Python

| Method | Description |
|--------|-------------|
| `__init__(embedding_dim=1536)` | Create with embedding dimension |
| `store(text, embedding) -> int` | Store text + embedding |
| `recall(query_embedding, max_steps=5) -> list` | Recall by dead reckoning |
| `navigate(tile_id, distance, heading) -> list` | Navigate from tile |
| `consolidate() -> int` | Merge nearby memories |
| `__len__()` | Memory count |

## Tests

**Rust**: 15 tests covering roundtrip, aperiodicity, Fibonacci ratio, 3-coloring, consolidation, navigation, large embeddings, confidence decay, and more.

**Python**: 10 tests covering the same core functionality.

## License

MIT