Metadata-Version: 2.4
Name: memory-molecule
Version: 0.1.0
Summary: Persistent memory for agentic systems — a faithful transposition of human memory architecture.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# memory-molecule

Persistent memory for agentic systems — a faithful transposition of human memory architecture into code.

## Installation

```bash
pip install memory-molecule
```

## Quickstart

```python
from memory_molecule import MemoryMolecule, MemoryConfig

# Initialize with a vault directory
config = MemoryConfig(vault_path="./my-vault", project="my-project")
mm = MemoryMolecule(config)

# Store a memory
mm.store("Decided to use PostgreSQL for persistence",
         memory_type="decision", importance="foundational")

# Recall memories by concept
results = mm.recall("database persistence")
for r in results:
    print(f"[{r['importance']}] {r['content'][:100]}")

# Apply memory decay (memories fade if not accessed)
report = mm.decay()
print(f"Archived {report.archived_count} stale memories")

# Session lifecycle
bundle = mm.on_session_start()  # Load relevant context
# ... do work ...
mm.on_session_end(commits=["abc123 feat: add auth"], decisions=["Use JWT tokens"])
```

## Tiered Memory Loading

memory-molecule loads context in three tiers to respect token budgets:

```python
from memory_molecule import MemoryLoader, MemoryConfig

loader = MemoryLoader(MemoryConfig(vault_path="./vault"))
result = loader.load(query="authentication", max_tokens=100000)

print(f"Tier 1: {result['tier1']['tokens']} tokens (always loaded)")
print(f"Tier 2: {result['tier2']['tokens']} tokens (recent context)")
print(f"Tier 3: {result['tier3']['tokens']} tokens (on-demand)")
```

| Tier | Target | Contents | Trigger |
|------|--------|----------|---------|
| 1 | 5K tokens | Invariants, latest context, git state | Always |
| 2 | 50K tokens | Recent sessions, decisions, phase docs | If budget allows |
| 3 | 150K tokens | Full journals, expertise, knowledge graph | Explicit query |

## Memory Types

| Type | Description | Importance Levels |
|------|-------------|-------------------|
| session | Session journals | context (default) |
| decision | Architectural decisions | foundational, hard_constraint |
| expertise | Learned patterns | foundational |
| knowledge | Domain knowledge | varies |

## Decay Model

Memories decay exponentially if not accessed:

- **Base decay**: `0.95^days` (half-life ~14 days)
- **Importance modifiers**: hard_constraint decays 2x slower, tactical decays 1.5x faster
- **Access reinforcement**: each access boosts relevance by 0.05 (max 0.3)
- **Archive threshold**: memories below 0.1 relevance are archived (not deleted)

## Observation Events

When configured, memory-molecule emits events to an observation server:

- `MemoryStore` — content written to vault
- `MemoryRecall` — search performed
- `MemoryDecay` — decay pass applied
- `MemorySessionStart` — session initialized
- `MemorySessionEnd` — session closed

Configure with `MemoryConfig(observation_url="http://localhost:4000/events")`.

## API Reference

### MemoryMolecule

| Method | Returns | Description |
|--------|---------|-------------|
| `store(content, memory_type, importance)` | `str` (path) | Write to vault |
| `recall(query, top_k)` | `list[dict]` | Search by concept |
| `decay()` | `DecayReport` | Apply relevance decay |
| `diff(session_a, session_b)` | `SessionDiff` | Compare sessions |
| `on_session_start()` | `RecallBundle` | Load session context |
| `on_session_end(commits, decisions)` | `None` | Close session |
| `consolidate(session_id)` | `str` | Summarize recent sessions |

### MemoryLoader

| Method | Returns | Description |
|--------|---------|-------------|
| `load_tier1()` | `dict` | Always-load context |
| `load_tier2(days)` | `dict` | Recent relevant context |
| `load_tier3(query)` | `dict` | On-demand deep context |
| `load(query, max_tokens)` | `dict` | Fill tiers to budget |

## Vision

This package is a community-extractable component of the [Oracle](https://github.com/rice0649/oracle) agentic engineering system. It implements a faithful transposition of human memory architecture:

| Human Memory | Agentic Equivalent | Status |
|-------------|-------------------|--------|
| Working memory | Context window | Built-in |
| Episodic memory | Session journals | Implemented |
| Semantic memory | Knowledge database | Implemented |
| Procedural memory | Expertise patterns | Implemented |
| Consolidation | Compression pass | Implemented |
| Forgetting curve | Exponential decay | Implemented |
| Associative recall | Importance-weighted search | Implemented |

## License

MIT
