etchmem 0.1.2__tar.gz → 0.1.4__tar.gz

{etchmem-0.1.2 → etchmem-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etchmem
-Version: 0.1.2
+Version: 0.1.4
 Summary: A pluggable, embeddable reconsolidating skill memory engine for AI agents
 Author: Andrey Olishchuk
 License: MIT
@@ -28,7 +28,13 @@ Dynamic: license-file
 
 # etchmem
 
-A lightweight, embeddable memory engine for LLM agents. Agents remember things, recall them later, and the stored knowledge quietly matures through use — no extra plumbing required.
+**Where agents grow up — not where they take notes.**
+
+Modern AI agents are built from skills. Every time a skill runs, it leaves a trail: results, feedback, corrections, surprises. That trail is experience — and experience is how an agent learns how the world actually works.
+
+`etchmem` is memory for that maturation. Not a scratchpad for the current session. Not a user profile to personalize replies. Not a long chat log you grep when context runs out. It is the layer where raw observations turn into durable understanding — how things work, what users react to, what failed last time — and keep sharpening every time the agent draws on it again.
+
+Over time, knowledge compounds. The agent stops merely following scenarios and starts carrying a worldview shaped by use.
 
 ```bash
 pip install etchmem
@@ -38,7 +44,7 @@ pip install etchmem
 
 ## What it is
 
-`etchmem` gives your agent a persistent memory that improves over time. You deposit raw observations, retrieve them with natural-language queries, and periodically consolidate — at which point the engine synthesizes scattered signals into compact knowledge articles and rewrites anything that's been recalled against fresh context.
+`etchmem` gives your agent a persistent memory that matures through living. You deposit raw observations — facts, outcomes, feedback — scoped to a skill or left general. You retrieve with natural-language queries. Periodically you consolidate, and the engine synthesizes scattered signal into compact knowledge articles, rewriting anything that has been recalled against fresh context.
 
 It is not a vector database and not an agent runtime. It sits above [ChromaDB](https://www.trychroma.com/), which handles all storage and embedding, and exposes exactly **three methods**.
 
@@ -52,7 +58,7 @@ Memory is kept in three tiers:
 - **Buffer** — a working space for deposits and recall-events, waiting for the next consolidation run.
 - **Injected** — synthesized knowledge articles, the primary search target. Only current knowledge is kept; superseded articles are hard-deleted.
 
-The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests.
+The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests. This is how a skill — or the agent as a whole — accumulates experience instead of starting from zero each run.
 
 Embeddings are computed locally by ChromaDB's built-in model — no external embedding API. Synthesis (the rewrite step inside `consolidate`) calls an LLM via `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
 

{etchmem-0.1.2 → etchmem-0.1.4}/README.md

@@ -1,6 +1,12 @@
 # etchmem
 
-A lightweight, embeddable memory engine for LLM agents. Agents remember things, recall them later, and the stored knowledge quietly matures through use — no extra plumbing required.
+**Where agents grow up — not where they take notes.**
+
+Modern AI agents are built from skills. Every time a skill runs, it leaves a trail: results, feedback, corrections, surprises. That trail is experience — and experience is how an agent learns how the world actually works.
+
+`etchmem` is memory for that maturation. Not a scratchpad for the current session. Not a user profile to personalize replies. Not a long chat log you grep when context runs out. It is the layer where raw observations turn into durable understanding — how things work, what users react to, what failed last time — and keep sharpening every time the agent draws on it again.
+
+Over time, knowledge compounds. The agent stops merely following scenarios and starts carrying a worldview shaped by use.
 
 ```bash
 pip install etchmem
@@ -10,7 +16,7 @@ pip install etchmem
 
 ## What it is
 
-`etchmem` gives your agent a persistent memory that improves over time. You deposit raw observations, retrieve them with natural-language queries, and periodically consolidate — at which point the engine synthesizes scattered signals into compact knowledge articles and rewrites anything that's been recalled against fresh context.
+`etchmem` gives your agent a persistent memory that matures through living. You deposit raw observations — facts, outcomes, feedback — scoped to a skill or left general. You retrieve with natural-language queries. Periodically you consolidate, and the engine synthesizes scattered signal into compact knowledge articles, rewriting anything that has been recalled against fresh context.
 
 It is not a vector database and not an agent runtime. It sits above [ChromaDB](https://www.trychroma.com/), which handles all storage and embedding, and exposes exactly **three methods**.
 
@@ -24,7 +30,7 @@ Memory is kept in three tiers:
 - **Buffer** — a working space for deposits and recall-events, waiting for the next consolidation run.
 - **Injected** — synthesized knowledge articles, the primary search target. Only current knowledge is kept; superseded articles are hard-deleted.
 
-The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests.
+The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests. This is how a skill — or the agent as a whole — accumulates experience instead of starting from zero each run.
 
 Embeddings are computed locally by ChromaDB's built-in model — no external embedding API. Synthesis (the rewrite step inside `consolidate`) calls an LLM via `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
 

{etchmem-0.1.2 → etchmem-0.1.4}/etchmem/consolidate/worker.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 import json
 import time
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import Any
 
 from etchmem.config import Config
@@ -53,6 +54,9 @@ accurate knowledge article from a set of raw signal fragments.
 ## Instructions
 - Write a single, cohesive knowledge article that captures all key facts.
 - Do NOT invent facts not present in the fragments.
+- Each fragment may be prefixed with a timestamp like `[21 Jun 2025, 15:25 UTC]`.
+  Preserve these timestamps verbatim inline, anchoring the facts they precede,
+  e.g. "As of 21 Jun 2025, 15:25 UTC, the deployment was rolled back."
 - At the end of the article, output a JSON block on its own line:
   {{"tags": {{"access_level": "...", "topic": "...", "product": "..."}}}}
 
@@ -74,6 +78,9 @@ accurate and incorporates the new information.
 - Preserve ALL load-bearing facts from the existing article.
 - Incorporate relevant new information from the fresh context.
 - Remove outdated claims only when the fresh context explicitly supersedes them.
+- Fresh context fragments may be prefixed with a timestamp like `[21 Jun 2025, 15:25 UTC]`.
+  Preserve these timestamps verbatim inline, anchoring the facts they precede.
+  Also carry forward any timestamps already present in the existing article.
 - At the end, output a JSON block on its own line:
   {{"tags": {{"access_level": "...", "topic": "...", "product": "..."}}}}
 
@@ -93,6 +100,13 @@ Reply with exactly one word: YES or NO.
 """
 
 
+def _stamp(ts: float) -> str:
+    """Format a Unix timestamp as a human-readable UTC string, e.g. '21 Jun 2025, 15:25 UTC'."""
+    if not ts:
+        return "unknown time"
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%-d %b %Y, %H:%M UTC")
+
+
 def _parse_synthesis_output(raw: str) -> tuple[str, dict]:
     """Split LLM output into (article_text, tags_dict)."""
     lines = raw.strip().split("\n")
@@ -351,8 +365,10 @@ class Worker:
                     return [item]
             return []
 
-        # Synthesize
-        fragments = "\n\n---\n\n".join(d.content for d in cluster.deposits)
+        # Synthesize — prefix each fragment with its absolute UTC timestamp
+        fragments = "\n\n---\n\n".join(
+            f"[{_stamp(d.created_at)}]\n{d.content}" for d in cluster.deposits
+        )
         prompt = _FORMATION_PROMPT.format(fragments=fragments)
         raw = self._connector.complete(prompt)
         article_text, tags = _parse_synthesis_output(raw)
@@ -396,8 +412,10 @@ class Worker:
                             current_articles[r.id] = item
                             break
 
-        # Fresh deposit content for the cluster
-        fresh_texts = [d.content for d in cluster.deposits]
+        # Fresh deposit content for the cluster — prefix with absolute UTC timestamps
+        fresh_texts = [
+            f"[{_stamp(d.created_at)}]\n{d.content}" for d in cluster.deposits
+        ]
         snapshots = [re.relational_snapshot for re in cluster.recall_events]
         all_fresh = fresh_texts + snapshots
         fresh_combined = "\n\n---\n\n".join(t for t in all_fresh if t.strip())

{etchmem-0.1.2 → etchmem-0.1.4}/etchmem/recall/recaller.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import time
 import uuid
+from datetime import datetime, timezone
 from typing import Any
 
 from etchmem.config import Config
@@ -87,13 +88,23 @@ class Recaller:
         merged = self._merge(injected_results, relational_results, top_k)
 
         # ── 4. Emit recall-event into buffer ──────────────────────────────
-        relational_snapshot = "\n\n".join(r.content for r in relational_results)
+        # Stamp each relational hit so time context survives into the snapshot
+        relational_snapshot = "\n\n".join(
+            f"[{self._stamp(r.created_at)}]\n{r.content}" for r in relational_results
+        )
         self._emit_recall_event(query, relational_snapshot, skill, hint)
 
         return merged
 
     # ── Helpers ───────────────────────────────────────────────────────────
 
+    @staticmethod
+    def _stamp(ts: float) -> str:
+        """Format a Unix timestamp as a human-readable UTC string."""
+        if not ts:
+            return "unknown time"
+        return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%-d %b %Y, %H:%M UTC")
+
     def _merge(
         self,
         injected: list[SearchResult],

{etchmem-0.1.2 → etchmem-0.1.4}/etchmem.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etchmem
-Version: 0.1.2
+Version: 0.1.4
 Summary: A pluggable, embeddable reconsolidating skill memory engine for AI agents
 Author: Andrey Olishchuk
 License: MIT
@@ -28,7 +28,13 @@ Dynamic: license-file
 
 # etchmem
 
-A lightweight, embeddable memory engine for LLM agents. Agents remember things, recall them later, and the stored knowledge quietly matures through use — no extra plumbing required.
+**Where agents grow up — not where they take notes.**
+
+Modern AI agents are built from skills. Every time a skill runs, it leaves a trail: results, feedback, corrections, surprises. That trail is experience — and experience is how an agent learns how the world actually works.
+
+`etchmem` is memory for that maturation. Not a scratchpad for the current session. Not a user profile to personalize replies. Not a long chat log you grep when context runs out. It is the layer where raw observations turn into durable understanding — how things work, what users react to, what failed last time — and keep sharpening every time the agent draws on it again.
+
+Over time, knowledge compounds. The agent stops merely following scenarios and starts carrying a worldview shaped by use.
 
 ```bash
 pip install etchmem
@@ -38,7 +44,7 @@ pip install etchmem
 
 ## What it is
 
-`etchmem` gives your agent a persistent memory that improves over time. You deposit raw observations, retrieve them with natural-language queries, and periodically consolidate — at which point the engine synthesizes scattered signals into compact knowledge articles and rewrites anything that's been recalled against fresh context.
+`etchmem` gives your agent a persistent memory that matures through living. You deposit raw observations — facts, outcomes, feedback — scoped to a skill or left general. You retrieve with natural-language queries. Periodically you consolidate, and the engine synthesizes scattered signal into compact knowledge articles, rewriting anything that has been recalled against fresh context.
 
 It is not a vector database and not an agent runtime. It sits above [ChromaDB](https://www.trychroma.com/), which handles all storage and embedding, and exposes exactly **three methods**.
 
@@ -52,7 +58,7 @@ Memory is kept in three tiers:
 - **Buffer** — a working space for deposits and recall-events, waiting for the next consolidation run.
 - **Injected** — synthesized knowledge articles, the primary search target. Only current knowledge is kept; superseded articles are hard-deleted.
 
-The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests.
+The key idea is **reconsolidation**: every `recall()` call emits a recall-event into the buffer. When you later call `consolidate()`, the engine detects which injected articles were used, checks whether fresh signal changes anything, and rewrites them if needed. Knowledge that gets recalled stays current as a side-effect of being recalled. Knowledge nobody asks about simply rests. This is how a skill — or the agent as a whole — accumulates experience instead of starting from zero each run.
 
 Embeddings are computed locally by ChromaDB's built-in model — no external embedding API. Synthesis (the rewrite step inside `consolidate`) calls an LLM via `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
 

{etchmem-0.1.2 → etchmem-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "etchmem"
-version = "0.1.2"
+version = "0.1.4"
 description = "A pluggable, embeddable reconsolidating skill memory engine for AI agents"
 readme = "README.md"
 license = { text = "MIT" }