# `memory.rs` – Memory Storage & Retrieval

## Purpose
Defines the **AI memory** model used for short‑term and long‑term contextual information. Memories are persisted under `~/.todozi/memories/`.

## Key Types
| Type | Description |
|------|-------------|
| `Memory` | Struct with fields `id`, `moment`, `meaning`, `reason`, `importance`, `term`, timestamps. |
| `MemoryCollection` | In‑memory map of `Memory`s with CRUD helpers and serialisation. |

## Public Functions
* `add_memory(memory: Memory) -> Result<()>` – stores a new memory.
* `list_memories(filter: Option<MemoryFilter>) -> Result<Vec<Memory>>` – retrieves memories, optionally filtered by term or importance.
* `search_memories(query: &str) -> Result<Vec<Memory>>` – thin wrapper around the embedding service for semantic search.

## Usage Example
```rust
use todozi::memory::{Memory, MemoryCollection};

fn main() -> todozi::error::Result<()> {
    // Create a new memory
    let mem = Memory::new(
        "2025-10-27 10:00".into(),
        "Discussed OAuth flow".into(),
        "Important for authentication".into(),
        9,
        MemoryTerm::Short,
    );

    // Add it to the collection (persisted on disk)
    add_memory(mem)?;

    // Retrieve all short‑term memories
    let short_memories = list_memories(Some(MemoryFilter::Term(MemoryTerm::Short)))?;
    for m in short_memories {
        println!("🧠 {} – {}", m.moment, m.meaning);
    }

    // Semantic search
    let results = search_memories("authentication")?;
    for r in results {
        println!("🔎 {} – {}", r.id, r.meaning);
    }

    Ok(())
}
```

## Integration Points
* **`emb.rs`** – Used for semantic search of memory content.
* **`todozi.rs`** – Structured‑text parser can extract `<memory>` blocks and feed them into this module.
* **CLI (`cli.rs`)** – Provides `todozi memory` sub‑commands (`create`, `list`, `show`).
* **Server (`server.rs`)** – Exposes `/memories` REST endpoints that call these functions.

## When to Use
- **Short‑term context** – Store recent conversation snippets or facts needed for ongoing AI interactions.
- **Long‑term knowledge** – Preserve important insights, design decisions, or project retrospectives.
- **Emotion‑aware AI** – Attach importance and term metadata so the system can prioritize recall.

---

*Generated by GPT‑OSS – documentation for the `memory.rs` module.*
