feat(memory): working-memory tier — capacity-bounded STM + STM→LTM promotion

[Sandermage]

Why

Point 2 of the memory-brain roadmap — the missing working-memory tier. The taxonomy (#77) made working memories decay fast; this adds the other two properties a real working memory has.

Stacked on #80 (reflection).

What

• prune_working(owner_id, capacity) — keep only the N most-recent working memories, evict the rest (a scratchpad, not an ever-growing log). Non-working memories untouched.
• promote_working(owner_id, min_access) — a working memory recalled ≥ min_access times graduates to a durable episodic memory (re-stored under the new type → slow decay; transient original dropped) — the classic STM→LTM promotion.
• run_maintenance now promotes-then-bounds the working tier per owner before consolidate+prune, so the background scheduler manages it automatically (the "nightly batch").

Pure engine ops over existing store primitives (no store-contract change).

TDD

test_memory_working_tier.py (6): capacity keeps the most-recent / ignores other kinds / no-op under capacity; promotion graduates used items to episodic / leaves below-threshold + non-working alone.

Verification

240 focused tests green (maintenance + engine + working + api + wiring); ruff-clean.

Remaining

Obsidian path-keyed dedup · typed entity/relation KG + LLM fact-extraction · GUI/TUI coherence (need a store find-by-property/update primitive or React/textual work — deliberate next slices).

[gemini-code-assist]

Code Review

This pull request introduces a working-memory tier to the memory engine, implementing capacity-bounded short-term pruning and short-term to long-term memory promotion during the maintenance pass, along with comprehensive unit tests. Feedback on these changes highlights a performance bottleneck and loss of graph connectivity in promote_working due to redundant embedding calls and deleted node associations, and suggests adding a defensive guard in prune_working to handle negative capacity values safely.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Redundant Embedding Call & Loss of Graph Associations during Promotion

There are two major issues with the current implementation of promote_working:

1. Performance Bottleneck (Redundant Embedding): Calling self.remember(...) triggers a new embedding call (self.embedder.embed_one(text)) for the node's content. Since the node is already stored and we have its embedding in node.embedding, re-embedding is highly inefficient and unnecessary. We should call self.store.add_node directly.
2. Loss of Graph Connectivity: Deleting the original node and creating a new one completely destroys all existing associations (such as Hebbian co_access edges and semantic similar_to edges) that the node accumulated while in working memory. To preserve these associations, we should retrieve the node's neighbors and re-create the edges for the newly promoted node before deleting the old one.

Suggested change

	self.remember(
	owner_id=owner_id,
	text=node.content,
	kind=to_kind,
	importance=node.importance,
	properties={**node.properties, "promoted_from": "working"},
	dedup=False,
	)
	neighbors = self.store.neighbors(node.id)
	new_id = self.store.add_node(
	owner_id=owner_id,
	kind=to_kind,
	content=node.content,
	embedding=node.embedding,
	importance=node.importance,
	properties={**(node.properties or {}), "promoted_from": "working"},
	)
	for neigh_id, rel, weight in neighbors:
	self.store.add_edge(new_id, neigh_id, rel, weight=weight)

[gemini-code-assist]

Defensive Guard for Negative Capacity

If capacity is negative, the slice working[capacity:] will slice from the end of the list (e.g., working[-1:]), which would evict only the most recent items instead of evicting everything or raising an error. Adding a defensive guard like capacity = max(0, capacity) ensures robust behavior.

Suggested change

	def prune_working(self, *, owner_id: int, capacity: int) -> int:
	"""Keep only the ``capacity`` most-recent ``working`` memories for this
	owner; evict the rest. Working memory is a scratchpad, not an
	ever-growing log — this is its capacity bound. Returns how many were
	evicted. Non-working memories are never touched."""
	working = [
	def prune_working(self, *, owner_id: int, capacity: int) -> int:
	"""Keep only the ``capacity`` most-recent ``working`` memories for this
	owner; evict the rest. Working memory is a scratchpad, not an
	ever-growing log — this is its capacity bound. Returns how many were
	evicted. Non-working memories are never touched."""
	capacity = max(0, capacity)
	working = [