etchmem 0.2.1__tar.gz → 0.3.0__tar.gz

{etchmem-0.2.1 → etchmem-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: etchmem
-Version: 0.2.1
-Summary: Python SDK for etchmem-server — the Knowledge Consolidation Engine for AI agents
+Version: 0.3.0
+Summary: Python SDK for etchmem-server 0.0.4 — the Knowledge Consolidation Engine for AI agents
 Author: Andrey Olishchuk
 License: MIT
 Project-URL: Repository, https://github.com/vossmoos/etchmem-sdk-python
@@ -30,6 +30,8 @@ Dynamic: license-file
 
 **Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
 
+Compatible with **etchmem-server 0.0.4**.
+
 Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
 
 This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
@@ -63,6 +65,44 @@ for hit in mem.recall("what did Acme sign?", top_k=5):
     print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
 ```
 
+### Three ways to ask
+
+Which one you want depends on what you already know. Reaching for the wrong one
+is a quiet source of wrong answers.
+
+| You know | Method | Returns |
+|---|---|---|
+| the subject | `know(ref)` | every belief about it — exhaustive, ordered by property |
+| only words | `recall(query)` | beliefs ranked by wording, `top_k` |
+| words, and want what they connect to | `associate(query)` | the above **plus** each subject's full facts **plus** connected nodes |
+
+```python
+# know — you have the subject
+facts = mem.know("MSM-0808")            # id or surface name; variants resolve
+for e in facts.settled(min_confidence=0.6):
+    print(e.property, "=", e.current_value)
+print(facts.contested, "open questions")
+
+# recall — you only have words. entity_id chains straight into know()
+for hit in mem.recall("bathroom leaks", top_k=5):
+    detail = mem.know(hit.entity_id)
+
+# associate — words, and what they connect to
+assoc = mem.associate("bathroom leaks")
+for node in assoc.nodes:
+    print(node["hops"], node["entity"]["name"], node["reached_via"])
+```
+
+`recall` is `ORDER BY similarity LIMIT top_k` with **no threshold** — it returns
+rows whatever their score, so an empty result means an empty scope rather than a
+failed search, and a returned row is not by itself evidence of a match. It also
+matches on the etch *narrative*, so an exact article number is compared by vector
+similarity, not string equality. When you know the subject, use `know`.
+
+`associate` follows declared relations one hop in both directions, so a fault
+reached by wording leads to the part that fixes it — which shares no word with
+the query.
+
 ### Async
 
 ```python
@@ -77,12 +117,14 @@ async with AsyncEtchMem("http://localhost:8000") as mem:
 
 ## API surface
 
-The SDK mirrors the seven REST endpoints one-to-one:
+The SDK mirrors the REST endpoints one-to-one:
 
 | Method | Endpoint | Returns |
 |---|---|---|
-| `remember(data, *, source, scope, extract_mode="deferred", metadata=None)` | `POST /remember` | `RememberResult` |
-| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None)` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `remember(data, *, source, scope, extract_mode="deferred", metadata=None, occurred_at=None)` | `POST /remember` | `RememberResult` |
+| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None, as_of_basis="ingest")` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `know(ref, *, as_of=None, entity_type=None, as_of_basis="ingest")` | `GET /entity/{ref}/etches` | `Knowledge` (iterable of `Etch`) |
+| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15)` | `POST /associate` | `Association` |
 | `sleep()` | `POST /sleep` | `SleepResult` |
 | `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
 | `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
@@ -95,14 +137,51 @@ All responses are plain dataclasses — see `etchmem/models.py`.
 
 `extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
 
-### recall with time-travel
+`occurred_at` (ISO-8601 or epoch seconds) declares when the content actually
+*happened*, as distinct from when you sent it. It defaults to ingest time, and
+**you must set it when loading historical records** — otherwise every signal in
+a backfill carries today's date, the server's recency policy has nothing to
+order by, and a 2009 answer competes with a 2022 answer as an equal.
 
-Pass `as_of` (ISO-8601) to recall what the system believed at that moment — for auditing decisions or incident forensics:
+```python
+res = mem.remember(
+    "Modul MSM-0808: NT-2405 is the correct supply up to revision C.",
+    source="ticket-resolved", scope="innoxel",
+    occurred_at="2014-03-17",
+)
+assert res.occurred_at_declared     # the parsed value is echoed back — check it
+```
+
+### know
+
+Every belief about one subject, exhaustive and ordered by property. `ref` is an
+entity id (`product_msm_0808`) or a surface name (`MSM-0808`, `MSM 0808`),
+resolved the way ingestion resolved it, so callers never need the internal id
+format. `Knowledge.settled(min_confidence)` filters to what is safe to state as
+fact; `.contested` counts the beliefs the engine could not settle, which belong
+in an internal note rather than a customer-facing answer.
+
+### time travel, and which clock
+
+Pass `as_of` (ISO-8601) to `recall`, `know` or `associate`. `as_of_basis` picks
+the clock:
+
+| Basis | Question it answers |
+|---|---|
+| `"ingest"` (default) | What did we **believe** then — what would this system have told a customer on that date. The question an audit or a dispute asks. |
+| `"event"` | What was **true** then, by the dates on the underlying facts. |
+
+They differ whenever a source reports late — a promotion on the 2nd that reached
+you on the 20th is invisible to ingest-basis on the 10th, visible to event-basis:
 
 ```python
-hits = mem.recall("Acme contract value", as_of="2026-06-01T00:00:00Z")
+mem.know("john@doe.com", as_of="2026-09-10")                       # believed
+mem.know("john@doe.com", as_of="2026-09-10", as_of_basis="event")  # was true
 ```
 
+Event-basis is only as good as your `occurred_at` discipline: signals deposited
+without it fall back to ingest time, and both bases then give the same answer.
+
 ### sleep
 
 The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
@@ -114,11 +193,14 @@ print(tick.etches_formed, tick.etches_updated, tick.contested)
 
 ### history
 
-Every belief change writes an immutable version snapshot:
+A version is written only when a belief actually **changes**, so six daily
+enrichment runs with one real change give you two versions, not six. Each
+carries both clocks:
 
 ```python
 for v in mem.history(etch_id):
     print(v.version, v.current_value, v.status, v.confidence)
+    print("  fact true from", v.event_at, "— we learned it", v.created_at)
 ```
 
 ---

etchmem-0.3.0/README.md

@@ -0,0 +1,219 @@
+# etchmem
+
+**Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
+
+Compatible with **etchmem-server 0.0.4**.
+
+Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
+
+This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
+
+```bash
+pip install etchmem
+```
+
+> **Note on MCP:** etchmem-server also exposes an MCP interface at `/mcp` with the same operations as tools. MCP clients (Claude, agent frameworks, IDEs) connect to it directly over the MCP protocol — no SDK needed. This package is for REST integrations only.
+
+---
+
+## Quickstart
+
+Run the server (see the etchmem-server repo — `docker compose up`), then:
+
+```python
+from etchmem import EtchMem
+
+mem = EtchMem("http://localhost:8000")   # default; also reads ETCHMEM_BASE_URL
+
+# Deposit a raw signal — no pre-structuring needed
+mem.remember(
+    "Acme signed the Q3 renewal at $40k. Maria approved the discount.",
+    source="agent-33",
+    scope="sales",
+)
+
+# Semantic recall over consolidated beliefs
+for hit in mem.recall("what did Acme sign?", top_k=5):
+    print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
+```
+
+### Three ways to ask
+
+Which one you want depends on what you already know. Reaching for the wrong one
+is a quiet source of wrong answers.
+
+| You know | Method | Returns |
+|---|---|---|
+| the subject | `know(ref)` | every belief about it — exhaustive, ordered by property |
+| only words | `recall(query)` | beliefs ranked by wording, `top_k` |
+| words, and want what they connect to | `associate(query)` | the above **plus** each subject's full facts **plus** connected nodes |
+
+```python
+# know — you have the subject
+facts = mem.know("MSM-0808")            # id or surface name; variants resolve
+for e in facts.settled(min_confidence=0.6):
+    print(e.property, "=", e.current_value)
+print(facts.contested, "open questions")
+
+# recall — you only have words. entity_id chains straight into know()
+for hit in mem.recall("bathroom leaks", top_k=5):
+    detail = mem.know(hit.entity_id)
+
+# associate — words, and what they connect to
+assoc = mem.associate("bathroom leaks")
+for node in assoc.nodes:
+    print(node["hops"], node["entity"]["name"], node["reached_via"])
+```
+
+`recall` is `ORDER BY similarity LIMIT top_k` with **no threshold** — it returns
+rows whatever their score, so an empty result means an empty scope rather than a
+failed search, and a returned row is not by itself evidence of a match. It also
+matches on the etch *narrative*, so an exact article number is compared by vector
+similarity, not string equality. When you know the subject, use `know`.
+
+`associate` follows declared relations one hop in both directions, so a fault
+reached by wording leads to the part that fixes it — which shares no word with
+the query.
+
+### Async
+
+```python
+from etchmem import AsyncEtchMem
+
+async with AsyncEtchMem("http://localhost:8000") as mem:
+    await mem.remember("...", source="agent-33", scope="sales")
+    hits = await mem.recall("what did Acme sign?")
+```
+
+---
+
+## API surface
+
+The SDK mirrors the REST endpoints one-to-one:
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `remember(data, *, source, scope, extract_mode="deferred", metadata=None, occurred_at=None)` | `POST /remember` | `RememberResult` |
+| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None, as_of_basis="ingest")` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `know(ref, *, as_of=None, entity_type=None, as_of_basis="ingest")` | `GET /entity/{ref}/etches` | `Knowledge` (iterable of `Etch`) |
+| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15)` | `POST /associate` | `Association` |
+| `sleep()` | `POST /sleep` | `SleepResult` |
+| `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
+| `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
+| `stats()` | `GET /stats` | `Stats` |
+| `health()` | `GET /health` | `Health` |
+
+All responses are plain dataclasses — see `etchmem/models.py`.
+
+### remember
+
+`extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
+
+`occurred_at` (ISO-8601 or epoch seconds) declares when the content actually
+*happened*, as distinct from when you sent it. It defaults to ingest time, and
+**you must set it when loading historical records** — otherwise every signal in
+a backfill carries today's date, the server's recency policy has nothing to
+order by, and a 2009 answer competes with a 2022 answer as an equal.
+
+```python
+res = mem.remember(
+    "Modul MSM-0808: NT-2405 is the correct supply up to revision C.",
+    source="ticket-resolved", scope="innoxel",
+    occurred_at="2014-03-17",
+)
+assert res.occurred_at_declared     # the parsed value is echoed back — check it
+```
+
+### know
+
+Every belief about one subject, exhaustive and ordered by property. `ref` is an
+entity id (`product_msm_0808`) or a surface name (`MSM-0808`, `MSM 0808`),
+resolved the way ingestion resolved it, so callers never need the internal id
+format. `Knowledge.settled(min_confidence)` filters to what is safe to state as
+fact; `.contested` counts the beliefs the engine could not settle, which belong
+in an internal note rather than a customer-facing answer.
+
+### time travel, and which clock
+
+Pass `as_of` (ISO-8601) to `recall`, `know` or `associate`. `as_of_basis` picks
+the clock:
+
+| Basis | Question it answers |
+|---|---|
+| `"ingest"` (default) | What did we **believe** then — what would this system have told a customer on that date. The question an audit or a dispute asks. |
+| `"event"` | What was **true** then, by the dates on the underlying facts. |
+
+They differ whenever a source reports late — a promotion on the 2nd that reached
+you on the 20th is invisible to ingest-basis on the 10th, visible to event-basis:
+
+```python
+mem.know("john@doe.com", as_of="2026-09-10")                       # believed
+mem.know("john@doe.com", as_of="2026-09-10", as_of_basis="event")  # was true
+```
+
+Event-basis is only as good as your `occurred_at` discipline: signals deposited
+without it fall back to ingest time, and both bases then give the same answer.
+
+### sleep
+
+The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
+
+```python
+tick = mem.sleep()
+print(tick.etches_formed, tick.etches_updated, tick.contested)
+```
+
+### history
+
+A version is written only when a belief actually **changes**, so six daily
+enrichment runs with one real change give you two versions, not six. Each
+carries both clocks:
+
+```python
+for v in mem.history(etch_id):
+    print(v.version, v.current_value, v.status, v.confidence)
+    print("  fact true from", v.event_at, "— we learned it", v.created_at)
+```
+
+---
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `base_url` | `ETCHMEM_BASE_URL` | `http://localhost:8000` |
+| `api_key` | `ETCHMEM_API_KEY` | none (sent as `Authorization: Bearer …` when set) |
+| `timeout` | — | 30 s |
+
+You can also inject your own `httpx.Client` / `httpx.AsyncClient` via the `client` parameter (custom TLS, proxies, retries).
+
+## Errors
+
+All SDK errors derive from `EtchMemError`:
+
+- `ConnectionError` — server unreachable (network / timeout)
+- `APIError` — non-2xx response (`.status_code`, `.detail`), with subclasses `NotFoundError` (404), `AuthenticationError` (401/403), `ServerError` (5xx)
+
+```python
+from etchmem import EtchMem, NotFoundError
+
+try:
+    mem.history("no-such-etch")
+except NotFoundError as e:
+    print(e.detail)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/
+```
+
+Releasing to PyPI: see [PIP-DEPLOY.md](PIP-DEPLOY.md).
+
+## License
+
+MIT

{etchmem-0.2.1 → etchmem-0.3.0}/etchmem/__init__.py

@@ -24,8 +24,8 @@ from etchmem.errors import (
     NotFoundError, ServerError,
 )
 from etchmem.models import (
-    Etch, EtchVersion, ExportResult, Health, History, RecallResponse,
-    RecallResult, RememberResult, SleepResult, Stats,
+    Association, EntityInfo, Etch, EtchVersion, ExportResult, Health, History,
+    Knowledge, RecallResponse, RecallResult, RememberResult, SleepResult, Stats,
 )
 
 __all__ = [
@@ -35,6 +35,9 @@ __all__ = [
     "RememberResult",
     "RecallResponse",
     "RecallResult",
+    "Association",
+    "EntityInfo",
+    "Knowledge",
     "SleepResult",
     "ExportResult",
     "Etch",
@@ -51,4 +54,4 @@ __all__ = [
     "ServerError",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{etchmem-0.2.1 → etchmem-0.3.0}/etchmem/async_client.py

@@ -63,9 +63,10 @@ class AsyncEtchMem:
     # ── internal ───────────────────────────────────────────────────────
 
     async def _request(self, method: str, path: str,
-                       json: dict[str, Any] | None = None) -> dict[str, Any]:
+                       json: dict[str, Any] | None = None,
+                       params: dict[str, Any] | None = None) -> dict[str, Any]:
         try:
-            resp = await self._client.request(method, path, json=json)
+            resp = await self._client.request(method, path, json=json, params=params)
         except httpx.HTTPError as e:
             raise ConnectionError(
                 f"etchmem server unreachable at {self.base_url}: {e}") from e
@@ -87,11 +88,13 @@ class AsyncEtchMem:
         scope: str,
         extract_mode: str = "deferred",
         metadata: dict[str, Any] | None = None,
+        occurred_at: str | float | None = None,
     ) -> RememberResult:
         """Deposit a raw text signal (see :meth:`etchmem.EtchMem.remember`)."""
         payload = await self._request("POST", "/remember", json={
             "data": data, "source": source, "scope": scope,
-            "extract_mode": extract_mode, "metadata": metadata or {}})
+            "extract_mode": extract_mode, "metadata": metadata or {},
+            "occurred_at": occurred_at})
         return RememberResult.from_dict(payload)
 
     async def recall(
@@ -103,13 +106,75 @@ class AsyncEtchMem:
         top_k: int = 5,
         include_signals: bool = True,
         as_of: str | None = None,
+        as_of_basis: str = "ingest",
     ) -> RecallResponse:
         """Semantic recall over etches; ``as_of`` enables time-travel."""
         payload = await self._request("POST", "/recall", json={
             "query": query, "scope": scope, "source": source, "top_k": top_k,
-            "include_signals": include_signals, "as_of": as_of})
+            "include_signals": include_signals, "as_of": as_of,
+            "as_of_basis": as_of_basis})
         return RecallResponse.from_dict(payload)
 
+
+
+
+    async def associate(
+        self,
+        query: str,
+        *,
+        scope: str | None = None,
+        top_k: int = 5,
+        hops: int = 1,
+        as_of: str | None = None,
+        min_score: float = 0.15,
+        as_of_basis: str = "ingest",
+    ) -> Association:
+        """What the memory holds for a phrase.
+
+        Use when you do NOT already know which entity you are asking about.
+        :meth:`recall` ranks beliefs by wording; this also returns every fact
+        about each matched subject and follows declared relations one hop, so a
+        fault reached by wording leads to the part that fixes it — which
+        wording alone never would.
+        """
+        payload = await self._request("POST", "/associate", json={
+            "query": query, "scope": scope, "top_k": top_k, "hops": hops,
+            "as_of": as_of, "min_score": min_score,
+            "as_of_basis": as_of_basis})
+        return Association.from_dict(payload)
+
+    async def know(
+        self,
+        ref: str,
+        *,
+        as_of: str | None = None,
+        entity_type: str | None = None,
+        as_of_basis: str = "ingest",
+    ) -> Knowledge:
+        """EVERY belief about one subject — exhaustive, unlike :meth:`recall`.
+
+        The counterpart to :meth:`recall`: recall retrieves by cue and may miss,
+        ``know`` is direct access to everything held about a subject.
+
+        ``recall`` ranks by embedding distance and returns ``top_k``, so a fact
+        can be absent from the answer without the caller being able to tell.
+        When the question is "what do we know about X", use this.
+
+        ``ref`` is an entity id (``product_msm_0808``) or a surface name
+        (``MSM-0808``, ``MSM 0808``), resolved the way ingestion resolved it.
+        ``as_of`` (ISO-8601) gives the beliefs as they stood then.
+        """
+        params: dict[str, Any] = {}
+        if as_of:
+            params["as_of"] = as_of
+        if entity_type:
+            params["entity_type"] = entity_type
+        if as_of_basis != "ingest":
+            params["as_of_basis"] = as_of_basis
+        payload = await self._request(
+            "GET", f"/entity/{ref}/etches", params=params or None)
+        return Knowledge.from_dict(payload)
+
     async def sleep(self) -> SleepResult:
         """Run one consolidation tick now (batch → extract → fold)."""
         return SleepResult.from_dict(await self._request("POST", "/sleep"))

{etchmem-0.2.1 → etchmem-0.3.0}/etchmem/client.py

@@ -72,9 +72,10 @@ class EtchMem:
     # ── internal ───────────────────────────────────────────────────────
 
     def _request(self, method: str, path: str,
-                 json: dict[str, Any] | None = None) -> dict[str, Any]:
+                 json: dict[str, Any] | None = None,
+                 params: dict[str, Any] | None = None) -> dict[str, Any]:
         try:
-            resp = self._client.request(method, path, json=json)
+            resp = self._client.request(method, path, json=json, params=params)
         except httpx.HTTPError as e:
             raise ConnectionError(
                 f"etchmem server unreachable at {self.base_url}: {e}") from e
@@ -96,16 +97,24 @@ class EtchMem:
         scope: str,
         extract_mode: str = "deferred",
         metadata: dict[str, Any] | None = None,
+        occurred_at: str | float | None = None,
     ) -> RememberResult:
         """Deposit a raw text signal.
 
         ``extract_mode='immediate'`` marks the signal urgent (extracted on
         the next worker tick); ``'deferred'`` (default) batches it cheaply.
         Idempotent: re-depositing identical content returns ``stored=False``.
+
+        ``occurred_at`` (ISO-8601 or epoch seconds) declares when the content
+        actually happened; it defaults to ingest time. Always set it when
+        loading historical records — otherwise every signal carries today's
+        date and the server cannot order them against each other. The result
+        echoes the parsed value so a bulk load can verify it was understood.
         """
         payload = self._request("POST", "/remember", json={
             "data": data, "source": source, "scope": scope,
-            "extract_mode": extract_mode, "metadata": metadata or {}})
+            "extract_mode": extract_mode, "metadata": metadata or {},
+            "occurred_at": occurred_at})
         return RememberResult.from_dict(payload)
 
     def recall(
@@ -117,6 +126,7 @@ class EtchMem:
         top_k: int = 5,
         include_signals: bool = True,
         as_of: str | None = None,
+        as_of_basis: str = "ingest",
     ) -> RecallResponse:
         """Semantic recall over consolidated etches (plus fresh raw signals).
 
@@ -125,9 +135,70 @@ class EtchMem:
         """
         payload = self._request("POST", "/recall", json={
             "query": query, "scope": scope, "source": source, "top_k": top_k,
-            "include_signals": include_signals, "as_of": as_of})
+            "include_signals": include_signals, "as_of": as_of,
+            "as_of_basis": as_of_basis})
         return RecallResponse.from_dict(payload)
 
+
+
+
+    def associate(
+        self,
+        query: str,
+        *,
+        scope: str | None = None,
+        top_k: int = 5,
+        hops: int = 1,
+        as_of: str | None = None,
+        min_score: float = 0.15,
+        as_of_basis: str = "ingest",
+    ) -> Association:
+        """What the memory holds for a phrase.
+
+        Use when you do NOT already know which entity you are asking about.
+        :meth:`recall` ranks beliefs by wording; this also returns every fact
+        about each matched subject and follows declared relations one hop, so a
+        fault reached by wording leads to the part that fixes it — which
+        wording alone never would.
+        """
+        payload = self._request("POST", "/associate", json={
+            "query": query, "scope": scope, "top_k": top_k, "hops": hops,
+            "as_of": as_of, "min_score": min_score,
+            "as_of_basis": as_of_basis})
+        return Association.from_dict(payload)
+
+    def know(
+        self,
+        ref: str,
+        *,
+        as_of: str | None = None,
+        entity_type: str | None = None,
+        as_of_basis: str = "ingest",
+    ) -> Knowledge:
+        """EVERY belief about one subject — exhaustive, unlike :meth:`recall`.
+
+        The counterpart to :meth:`recall`: recall retrieves by cue and may miss,
+        ``know`` is direct access to everything held about a subject.
+
+        ``recall`` ranks by embedding distance and returns ``top_k``, so a fact
+        can be absent from the answer without the caller being able to tell.
+        When the question is "what do we know about X", use this.
+
+        ``ref`` is an entity id (``product_msm_0808``) or a surface name
+        (``MSM-0808``, ``MSM 0808``), resolved the way ingestion resolved it.
+        ``as_of`` (ISO-8601) gives the beliefs as they stood then.
+        """
+        params: dict[str, Any] = {}
+        if as_of:
+            params["as_of"] = as_of
+        if entity_type:
+            params["entity_type"] = entity_type
+        if as_of_basis != "ingest":
+            params["as_of_basis"] = as_of_basis
+        payload = self._request(
+            "GET", f"/entity/{ref}/etches", params=params or None)
+        return Knowledge.from_dict(payload)
+
     def sleep(self) -> SleepResult:
         """Run one consolidation tick now (batch → extract → fold)."""
         return SleepResult.from_dict(self._request("POST", "/sleep"))

{etchmem-0.2.1 → etchmem-0.3.0}/etchmem/models.py

@@ -16,11 +16,84 @@ class RememberResult:
     stored: bool
     status: str          # "new" | "duplicate"
     message: str
+    occurred_at: float = 0.0        # event time as stored, epoch seconds
+    occurred_at_declared: bool = False   # False = ingest time was used
 
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> "RememberResult":
         return cls(id=d["id"], stored=d["stored"], status=d["status"],
-                   message=d.get("message", ""))
+                   message=d.get("message", ""),
+                   occurred_at=d.get("occurred_at", 0.0) or 0.0,
+                   occurred_at_declared=bool(d.get("occurred_at_declared", False)))
+
+
+@dataclass
+class Association:
+    """What the memory holds for a phrase: beliefs, subjects, connected nodes."""
+    query: str
+    seeds: list[Any]
+    nodes: list[Any]
+    edges: list[Any]
+    contested: int = 0
+    as_of: str | None = None
+
+    def named(self, *types: str) -> list[Any]:
+        """Nodes of these entity types, closest first."""
+        return [n for n in self.nodes if not types or n["entity"]["type"] in types]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Association":
+        return cls(query=d["query"], seeds=d.get("seeds") or [],
+                   nodes=d.get("nodes") or [], edges=d.get("edges") or [],
+                   contested=d.get("contested", 0), as_of=d.get("as_of"))
+
+
+@dataclass
+class EntityInfo:
+    """The canonical subject an Knowledge answer is about."""
+    id: str
+    name: str
+    type: str
+    aliases: list[str]
+    scope: str | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "EntityInfo":
+        return cls(id=d["id"], name=d["name"], type=d["type"],
+                   aliases=list(d.get("aliases") or []), scope=d.get("scope"))
+
+
+@dataclass
+class Knowledge:
+    """Every belief about one subject — exhaustive, not similarity-ranked."""
+    entity: EntityInfo
+    etches: list["Etch"]
+    count: int = 0
+    as_of: str | None = None
+    contested: int = 0
+
+    def __iter__(self):
+        return iter(self.etches)
+
+    def __len__(self) -> int:
+        return len(self.etches)
+
+    def settled(self, min_confidence: float = 0.0) -> list["Etch"]:
+        """Only beliefs safe to state as fact.
+
+        A contested belief is one the engine could not settle; surfacing it as
+        an answer is the failure this whole design exists to prevent. Use the
+        contested ones to raise a question instead.
+        """
+        return [e for e in self.etches
+                if e.status == "settled" and e.confidence >= min_confidence]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Knowledge":
+        return cls(entity=EntityInfo.from_dict(d["entity"]),
+                   etches=[Etch.from_dict(e) for e in d.get("etches") or []],
+                   count=d.get("count", 0), as_of=d.get("as_of"),
+                   contested=d.get("contested", 0))
 
 
 @dataclass
@@ -30,6 +103,7 @@ class RecallResult:
     content: str
     score: float
     origin: str                     # "etch" | "signal"
+    entity_id: str | None = None    # subject slug — pass straight to know()
     entity_name: str | None = None
     property: str | None = None
     value: str | None = None
@@ -44,7 +118,7 @@ class RecallResult:
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> "RecallResult":
         return cls(**{k: d.get(k) for k in (
-            "id", "content", "score", "origin", "entity_name", "property",
+            "id", "content", "score", "origin", "entity_id", "entity_name", "property",
             "value", "status", "confidence", "version", "scope", "source",
             "updated_at")} | {"created_at": d.get("created_at", 0.0)})
 

{etchmem-0.2.1 → etchmem-0.3.0}/etchmem.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: etchmem
-Version: 0.2.1
-Summary: Python SDK for etchmem-server — the Knowledge Consolidation Engine for AI agents
+Version: 0.3.0
+Summary: Python SDK for etchmem-server 0.0.4 — the Knowledge Consolidation Engine for AI agents
 Author: Andrey Olishchuk
 License: MIT
 Project-URL: Repository, https://github.com/vossmoos/etchmem-sdk-python
@@ -30,6 +30,8 @@ Dynamic: license-file
 
 **Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
 
+Compatible with **etchmem-server 0.0.4**.
+
 Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
 
 This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
@@ -63,6 +65,44 @@ for hit in mem.recall("what did Acme sign?", top_k=5):
     print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
 ```
 
+### Three ways to ask
+
+Which one you want depends on what you already know. Reaching for the wrong one
+is a quiet source of wrong answers.
+
+| You know | Method | Returns |
+|---|---|---|
+| the subject | `know(ref)` | every belief about it — exhaustive, ordered by property |
+| only words | `recall(query)` | beliefs ranked by wording, `top_k` |
+| words, and want what they connect to | `associate(query)` | the above **plus** each subject's full facts **plus** connected nodes |
+
+```python
+# know — you have the subject
+facts = mem.know("MSM-0808")            # id or surface name; variants resolve
+for e in facts.settled(min_confidence=0.6):
+    print(e.property, "=", e.current_value)
+print(facts.contested, "open questions")
+
+# recall — you only have words. entity_id chains straight into know()
+for hit in mem.recall("bathroom leaks", top_k=5):
+    detail = mem.know(hit.entity_id)
+
+# associate — words, and what they connect to
+assoc = mem.associate("bathroom leaks")
+for node in assoc.nodes:
+    print(node["hops"], node["entity"]["name"], node["reached_via"])
+```
+
+`recall` is `ORDER BY similarity LIMIT top_k` with **no threshold** — it returns
+rows whatever their score, so an empty result means an empty scope rather than a
+failed search, and a returned row is not by itself evidence of a match. It also
+matches on the etch *narrative*, so an exact article number is compared by vector
+similarity, not string equality. When you know the subject, use `know`.
+
+`associate` follows declared relations one hop in both directions, so a fault
+reached by wording leads to the part that fixes it — which shares no word with
+the query.
+
 ### Async
 
 ```python
@@ -77,12 +117,14 @@ async with AsyncEtchMem("http://localhost:8000") as mem:
 
 ## API surface
 
-The SDK mirrors the seven REST endpoints one-to-one:
+The SDK mirrors the REST endpoints one-to-one:
 
 | Method | Endpoint | Returns |
 |---|---|---|
-| `remember(data, *, source, scope, extract_mode="deferred", metadata=None)` | `POST /remember` | `RememberResult` |
-| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None)` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `remember(data, *, source, scope, extract_mode="deferred", metadata=None, occurred_at=None)` | `POST /remember` | `RememberResult` |
+| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None, as_of_basis="ingest")` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `know(ref, *, as_of=None, entity_type=None, as_of_basis="ingest")` | `GET /entity/{ref}/etches` | `Knowledge` (iterable of `Etch`) |
+| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15)` | `POST /associate` | `Association` |
 | `sleep()` | `POST /sleep` | `SleepResult` |
 | `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
 | `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
@@ -95,14 +137,51 @@ All responses are plain dataclasses — see `etchmem/models.py`.
 
 `extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
 
-### recall with time-travel
+`occurred_at` (ISO-8601 or epoch seconds) declares when the content actually
+*happened*, as distinct from when you sent it. It defaults to ingest time, and
+**you must set it when loading historical records** — otherwise every signal in
+a backfill carries today's date, the server's recency policy has nothing to
+order by, and a 2009 answer competes with a 2022 answer as an equal.
 
-Pass `as_of` (ISO-8601) to recall what the system believed at that moment — for auditing decisions or incident forensics:
+```python
+res = mem.remember(
+    "Modul MSM-0808: NT-2405 is the correct supply up to revision C.",
+    source="ticket-resolved", scope="innoxel",
+    occurred_at="2014-03-17",
+)
+assert res.occurred_at_declared     # the parsed value is echoed back — check it
+```
+
+### know
+
+Every belief about one subject, exhaustive and ordered by property. `ref` is an
+entity id (`product_msm_0808`) or a surface name (`MSM-0808`, `MSM 0808`),
+resolved the way ingestion resolved it, so callers never need the internal id
+format. `Knowledge.settled(min_confidence)` filters to what is safe to state as
+fact; `.contested` counts the beliefs the engine could not settle, which belong
+in an internal note rather than a customer-facing answer.
+
+### time travel, and which clock
+
+Pass `as_of` (ISO-8601) to `recall`, `know` or `associate`. `as_of_basis` picks
+the clock:
+
+| Basis | Question it answers |
+|---|---|
+| `"ingest"` (default) | What did we **believe** then — what would this system have told a customer on that date. The question an audit or a dispute asks. |
+| `"event"` | What was **true** then, by the dates on the underlying facts. |
+
+They differ whenever a source reports late — a promotion on the 2nd that reached
+you on the 20th is invisible to ingest-basis on the 10th, visible to event-basis:
 
 ```python
-hits = mem.recall("Acme contract value", as_of="2026-06-01T00:00:00Z")
+mem.know("john@doe.com", as_of="2026-09-10")                       # believed
+mem.know("john@doe.com", as_of="2026-09-10", as_of_basis="event")  # was true
 ```
 
+Event-basis is only as good as your `occurred_at` discipline: signals deposited
+without it fall back to ingest time, and both bases then give the same answer.
+
 ### sleep
 
 The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
@@ -114,11 +193,14 @@ print(tick.etches_formed, tick.etches_updated, tick.contested)
 
 ### history
 
-Every belief change writes an immutable version snapshot:
+A version is written only when a belief actually **changes**, so six daily
+enrichment runs with one real change give you two versions, not six. Each
+carries both clocks:
 
 ```python
 for v in mem.history(etch_id):
     print(v.version, v.current_value, v.status, v.confidence)
+    print("  fact true from", v.event_at, "— we learned it", v.created_at)
 ```
 
 ---

{etchmem-0.2.1 → etchmem-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "etchmem"
-version = "0.2.1"
-description = "Python SDK for etchmem-server — the Knowledge Consolidation Engine for AI agents"
+version = "0.3.0"
+description = "Python SDK for etchmem-server 0.0.4 — the Knowledge Consolidation Engine for AI agents"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.11"

etchmem-0.2.1/README.md

@@ -1,137 +0,0 @@
-# etchmem
-
-**Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
-
-Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
-
-This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
-
-```bash
-pip install etchmem
-```
-
-> **Note on MCP:** etchmem-server also exposes an MCP interface at `/mcp` with the same operations as tools. MCP clients (Claude, agent frameworks, IDEs) connect to it directly over the MCP protocol — no SDK needed. This package is for REST integrations only.
-
----
-
-## Quickstart
-
-Run the server (see the etchmem-server repo — `docker compose up`), then:
-
-```python
-from etchmem import EtchMem
-
-mem = EtchMem("http://localhost:8000")   # default; also reads ETCHMEM_BASE_URL
-
-# Deposit a raw signal — no pre-structuring needed
-mem.remember(
-    "Acme signed the Q3 renewal at $40k. Maria approved the discount.",
-    source="agent-33",
-    scope="sales",
-)
-
-# Semantic recall over consolidated beliefs
-for hit in mem.recall("what did Acme sign?", top_k=5):
-    print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
-```
-
-### Async
-
-```python
-from etchmem import AsyncEtchMem
-
-async with AsyncEtchMem("http://localhost:8000") as mem:
-    await mem.remember("...", source="agent-33", scope="sales")
-    hits = await mem.recall("what did Acme sign?")
-```
-
----
-
-## API surface
-
-The SDK mirrors the seven REST endpoints one-to-one:
-
-| Method | Endpoint | Returns |
-|---|---|---|
-| `remember(data, *, source, scope, extract_mode="deferred", metadata=None)` | `POST /remember` | `RememberResult` |
-| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None)` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
-| `sleep()` | `POST /sleep` | `SleepResult` |
-| `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
-| `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
-| `stats()` | `GET /stats` | `Stats` |
-| `health()` | `GET /health` | `Health` |
-
-All responses are plain dataclasses — see `etchmem/models.py`.
-
-### remember
-
-`extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
-
-### recall with time-travel
-
-Pass `as_of` (ISO-8601) to recall what the system believed at that moment — for auditing decisions or incident forensics:
-
-```python
-hits = mem.recall("Acme contract value", as_of="2026-06-01T00:00:00Z")
-```
-
-### sleep
-
-The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
-
-```python
-tick = mem.sleep()
-print(tick.etches_formed, tick.etches_updated, tick.contested)
-```
-
-### history
-
-Every belief change writes an immutable version snapshot:
-
-```python
-for v in mem.history(etch_id):
-    print(v.version, v.current_value, v.status, v.confidence)
-```
-
----
-
-## Configuration
-
-| Parameter | Env var | Default |
-|---|---|---|
-| `base_url` | `ETCHMEM_BASE_URL` | `http://localhost:8000` |
-| `api_key` | `ETCHMEM_API_KEY` | none (sent as `Authorization: Bearer …` when set) |
-| `timeout` | — | 30 s |
-
-You can also inject your own `httpx.Client` / `httpx.AsyncClient` via the `client` parameter (custom TLS, proxies, retries).
-
-## Errors
-
-All SDK errors derive from `EtchMemError`:
-
-- `ConnectionError` — server unreachable (network / timeout)
-- `APIError` — non-2xx response (`.status_code`, `.detail`), with subclasses `NotFoundError` (404), `AuthenticationError` (401/403), `ServerError` (5xx)
-
-```python
-from etchmem import EtchMem, NotFoundError
-
-try:
-    mem.history("no-such-etch")
-except NotFoundError as e:
-    print(e.detail)
-```
-
----
-
-## Development
-
-```bash
-pip install -e ".[dev]"
-python -m pytest tests/
-```
-
-Releasing to PyPI: see [PIP-DEPLOY.md](PIP-DEPLOY.md).
-
-## License
-
-MIT