feat(v1): dual-channel groundwork

- Add pluggable embeddings providers (hash fallback, ST, OpenAI)
- Add in-memory cosine vector index and session TTL store
- Add summarizers (heuristic, OpenAI)
- Add v1 endpoints: embed, store, search, checkpoint, restore
- Add openapi/openapi-v1.yaml
- Update Python/TS clients with v1 helpers
- Update README for v1 overview

Note: follow-up will address remaining lint (line length).

Author: AlmostBald-TRADING

README.md

@@ -24,13 +24,23 @@ uvicorn src.contextforge_memory.main:app --host 0.0.0.0 --port 8085
 - `POST /v0/search`
 - `POST /v0/embed`
 
+### v1 (enabled by default; set `CF_ENABLE_V1=false` to disable)
+
+- `POST /v1/embed` (provider-backed)
+- `POST /v1/store` (accepts optional `vectors`, updates vector index)
+- `POST /v1/search` (vector search)
+- `POST /v1/checkpoint` (ephemeral session checkpoint)
+- `POST /v1/restore` (stitched context: recent checkpoints + relevant memory)
+
 See `openapi/openapi-v0.yaml` for schemas.
 
 ## Clients
 
 - Python: `clients/python/contextforge_client.py`
 - TypeScript: `clients/typescript/contextforgeClient.ts`
 
+Both clients now expose v1 helpers (prefixed with `v1*`).
+
 ## CI
 
 Basic import smoke in GitHub Actions (see `.github/workflows/ci.yml`).

clients/python/contextforge_client.py

@@ -5,9 +5,10 @@
 
 
 class ContextForgeClient:
-    def __init__(self, base_url: str) -> None:
+    def __init__(self, base_url: str, api_key: str | None = None) -> None:
         self.base_url = base_url.rstrip("/")
         self._client = httpx.Client(timeout=15.0)
+        self._headers = {"x-api-key": api_key} if api_key else {}
 
     def health(self) -> Dict[str, Any]:
         r = self._client.get(f"{self.base_url}/v0/health")
@@ -40,3 +41,72 @@ def embed(self, texts: List[str]) -> Dict[str, Any]:
         )
         r.raise_for_status()
         return r.json()
+
+    # v1 API
+    def v1_store(
+        self, items: List[Dict[str, Any]], vectors: List[List[float]] | None = None
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"items": items}
+        if vectors is not None:
+            payload["vectors"] = vectors
+        r = self._client.post(
+            f"{self.base_url}/v1/store",
+            json=payload,
+            headers=self._headers,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def v1_search(
+        self, namespace: str, project_id: str, query: str, top_k: int = 5
+    ) -> Dict[str, Any]:
+        payload = {
+            "namespace": namespace,
+            "project_id": project_id,
+            "query": query,
+            "top_k": top_k,
+        }
+        r = self._client.post(
+            f"{self.base_url}/v1/search",
+            json=payload,
+            headers=self._headers,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def v1_embed(self, texts: List[str]) -> Dict[str, Any]:
+        r = self._client.post(
+            f"{self.base_url}/v1/embed",
+            json={"texts": texts},
+            headers=self._headers,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def v1_checkpoint(
+        self,
+        session_id: str,
+        phase: str,
+        summary: str | None = None,
+        metadata: Dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"session_id": session_id, "phase": phase}
+        if summary is not None:
+            payload["summary"] = summary
+        if metadata is not None:
+            payload["metadata"] = metadata
+        r = self._client.post(
+            f"{self.base_url}/v1/checkpoint", json=payload, headers=self._headers
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def v1_restore(self, session_id: str, task: str, top_k: int = 5) -> Dict[str, Any]:
+        payload = {"session_id": session_id, "task": task, "top_k": top_k}
+        r = self._client.post(
+            f"{self.base_url}/v1/restore",
+            json=payload,
+            headers=self._headers,
+        )
+        r.raise_for_status()
+        return r.json()

clients/typescript/contextforgeClient.ts

@@ -9,9 +9,11 @@ export type MemoryItem = {
 
 export class ContextForgeClient {
   private baseUrl: string;
+  private apiKey?: string;
 
-  constructor(baseUrl: string) {
+  constructor(baseUrl: string, apiKey?: string) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
   }
 
   async health(): Promise<{ status: string }> {
@@ -49,6 +51,68 @@ export class ContextForgeClient {
     if (!r.ok) throw new Error(`embed failed: ${r.status}`);
     return r.json();
   }
+
+  // v1 API
+  private authHeaders(): Record<string, string> {
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.apiKey) h["x-api-key"] = this.apiKey;
+    return h;
+  }
+
+  async v1Store(items: MemoryItem[], vectors?: number[][]): Promise<{ stored: number }> {
+    const body: any = { items };
+    if (vectors) body.vectors = vectors;
+    const r = await fetch(`${this.baseUrl}/v1/store`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) throw new Error(`v1 store failed: ${r.status}`);
+    return r.json();
+  }
+
+  async v1Search(namespace: string, project_id: string, query: string, top_k = 5): Promise<{ results: MemoryItem[] }> {
+    const r = await fetch(`${this.baseUrl}/v1/search`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify({ namespace, project_id, query, top_k }),
+    });
+    if (!r.ok) throw new Error(`v1 search failed: ${r.status}`);
+    return r.json();
+  }
+
+  async v1Embed(texts: string[]): Promise<{ vectors: number[][] }> {
+    const r = await fetch(`${this.baseUrl}/v1/embed`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify({ texts }),
+    });
+    if (!r.ok) throw new Error(`v1 embed failed: ${r.status}`);
+    return r.json();
+  }
+
+  async v1Checkpoint(session_id: string, phase: string, summary?: string, metadata?: Record<string, unknown>): Promise<{ ok: boolean }> {
+    const body: any = { session_id, phase };
+    if (summary) body.summary = summary;
+    if (metadata) body.metadata = metadata;
+    const r = await fetch(`${this.baseUrl}/v1/checkpoint`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) throw new Error(`v1 checkpoint failed: ${r.status}`);
+    return r.json();
+  }
+
+  async v1Restore(session_id: string, task: string, top_k = 5): Promise<{ context: string }> {
+    const r = await fetch(`${this.baseUrl}/v1/restore`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify({ session_id, task, top_k }),
+    });
+    if (!r.ok) throw new Error(`v1 restore failed: ${r.status}`);
+    return r.json();
+  }
 }