[Hackathon] openai-llm: semantic memory plugin (recall + TTL + LRU)

README.md

@@ -231,7 +231,7 @@ resolved by name via entry points or a built-in default.
 |  7 | Payments      | `Payments`      | `prepaid_credits` (in-memory ledger) |
 |  8 | Coordination  | `Coordination`  | `contract_net` (FIPA: propose · bid · resolve · commit) |
 |  9 | Negotiation   | `Negotiation`   | `alternating_offers` (Rubinstein, with patience discount) |
-| 10 | Memory        | `Memory`        | `blackboard` (shared KV, subscribe, CAS) |
+| 10 | Memory        | `Memory`        | `blackboard` (shared KV, subscribe, CAS); also ships `semantic` (similarity recall + TTL + LRU) |
 | 11 | Privacy       | `Privacy`       | `noop` (stub passthrough) |
 | 12 | Data Facts    | `DataFacts`     | `datafacts_v1` (dataset publish · fetch · ACL) |
 

docs/layers/memory.md

@@ -15,16 +15,47 @@ class Memory(Protocol):
 
 Full definition: [`nest_core/layers/memory.py`](../../packages/nest-core/nest_core/layers/memory.py).
 
-## Default plugin
+## Built-in plugins
 
-`blackboard` — shared in-process dict with subscribe + CAS.
+| Name | What it is | When to use |
+|---|---|---|
+| `blackboard` (default) | Shared in-process dict with subscribe + CAS. | Coordination via shared state; you already know the key you want. |
+| `semantic` | Drop-in `Memory` with **similarity recall**, **TTL**, and **LRU eviction**. Deterministic hashed-trigram embedder, no API key required. | Retrieval-augmented LLM agents; stressing what gets remembered vs. evicted under capacity bounds. |
 
-Source: [`nest_plugins_reference/memory/blackboard.py`](../../packages/nest-plugins-reference/nest_plugins_reference/memory/blackboard.py).
+Sources:
+- [`nest_plugins_reference/memory/blackboard.py`](../../packages/nest-plugins-reference/nest_plugins_reference/memory/blackboard.py)
+- [`nest_plugins_reference/memory/semantic.py`](../../packages/nest-plugins-reference/nest_plugins_reference/memory/semantic.py)
+
+### `semantic` — extra surface
+
+Implements the full `Memory` protocol so it slots in anywhere
+`blackboard` does. On top of that:
+
+```python
+mem = SemanticMemory(capacity=128, ttl=100)
+await mem.write("buyer-3:greet", b"hello, I want to buy apples")
+[hit] = await mem.recall("apple buyer", k=1)
+hit.key    # "buyer-3:greet"
+hit.score  # cosine similarity, in [-1, 1]
+await mem.forget("buyer-3:greet")
+mem.stats()  # {size, capacity, writes, recalls, evictions, expirations, tick}
+```
+
+The embedder is a deterministic hashed bag of (tokens + character
+trigrams) — so `recall("apple")` finds memories mentioning "apples"
+without any external service and without breaking NEST's "same seed
+→ identical trace" guarantee.
+
+For a learned embedding model, wrap the OpenAI/Anthropic embeddings
+API behind the same surface and register it as a separate plugin
+(e.g. `memory:openai_embeddings`). That one will *not* be
+deterministic — keep it for Tier 2 only.
 
 ## Writing your own
 
 See [`writing-a-plugin.md`](../writing-a-plugin.md). Register under
 entry point group `nest.plugins.memory`.
 
 Good fits to test here: CRDTs (LWW-Register, OR-Set), tuple spaces,
-eventually-consistent stores, snapshot isolation.
+eventually-consistent stores, snapshot isolation, vector stores
+(FAISS / pgvector / Chroma) behind the `semantic` surface.

packages/nest-core/nest_core/plugins.py

@@ -29,6 +29,7 @@
         f"{_REF}.negotiation.alternating_offers:AlternatingOffers"
     ),
     ("memory", "blackboard"): f"{_REF}.memory.blackboard:Blackboard",
+    ("memory", "semantic"): f"{_REF}.memory.semantic:SemanticMemory",
     ("privacy", "noop"): f"{_REF}.privacy.noop:NoopPrivacy",
     ("datafacts", "datafacts_v1"): f"{_REF}.datafacts.datafacts_v1:DataFactsV1",
 }

packages/nest-plugins-reference/nest_plugins_reference/memory/__init__.py

@@ -1 +1,14 @@
 # SPDX-License-Identifier: Apache-2.0
+"""Memory layer reference plugins.
+
+- ``blackboard`` (built-in default): shared KV store with subscribe/CAS.
+- ``semantic``: drop-in ``Memory`` with similarity recall, TTL, and LRU
+  eviction. Designed for retrieval-augmented LLM agent swarms while
+  staying deterministic for Tier 1 simulation.
+"""
+
+from nest_plugins_reference.memory.blackboard import Blackboard as Blackboard
+from nest_plugins_reference.memory.semantic import RecallHit as RecallHit
+from nest_plugins_reference.memory.semantic import SemanticMemory as SemanticMemory
+
+__all__ = ["Blackboard", "RecallHit", "SemanticMemory"]