Initial commit: ConextForge Memory MCP v0

- FastAPI-based memory service with store, search, and embed APIs
- Versioned API at /v0/ with deterministic hash-based embeddings
- JSONL storage backend with namespace/project filtering
- Python and TypeScript client implementations
- OpenAPI specification and CI workflow
- Comprehensive smoke tests passing

Author: AlmostBald-TRADING

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{py,rs,go,ts,tsx}]
+indent_size = 4
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
+
+

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: Lint
+        run: |
+          ruff check src || true
+      - name: Import smoke
+        run: |
+          python - << 'PY'
+          import importlib
+          import sys
+          sys.path.append('src')
+          import contextforge_memory
+          from contextforge_memory.main import app
+          print('ok')
+          PY
+
+

.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+.venv/
+.env
+.env.*
+.DS_Store
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+.coverage
+coverage.xml
+.idea/
+.vscode/
+node_modules/
+logs/
+data/
+
+

LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 bofh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

Makefile

@@ -0,0 +1,16 @@
+run:
+	uvicorn src.contextforge_memory.main:app --host 0.0.0.0 --port 8085
+
+install:
+	python -m pip install -r requirements.txt
+
+format:
+	python -m pip install black && black src clients || true
+
+lint:
+	python -m pip install ruff && ruff check src || true
+
+smoke:
+	python -c "import contextforge_memory; from contextforge_memory.main import app; print('ok')"
+
+

README.md

@@ -0,0 +1,32 @@
+## ContextForge Memory (v0)
+
+Lightweight external memory layer providing store, search, and embed APIs for multi-repo reuse (Brainstorm, Cursor, and others).
+
+### Features
+- Versioned API: `/v0/` with `store`, `search`, `embed`.
+- Deterministic, minimal embedding (hash-based) for baseline functionality.
+- Pluggable storage (default: JSONL on disk).
+
+### Quickstart
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn src.contextforge_memory.main:app --host 0.0.0.0 --port 8085
+```
+
+### API Endpoints
+- `GET /v0/health`
+- `POST /v0/store`
+- `POST /v0/search`
+- `POST /v0/embed`
+
+See `openapi/openapi-v0.yaml` for schemas.
+
+### Clients
+- Python: `clients/python/contextforge_client.py`
+- TypeScript: `clients/typescript/contextforgeClient.ts`
+
+### CI
+Basic import smoke in GitHub Actions (see `.github/workflows/ci.yml`).
+
+

clients/python/contextforge_client.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+import httpx
+
+
+class ContextForgeClient:
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=15.0)
+
+    def health(self) -> Dict[str, Any]:
+        r = self._client.get(f"{self.base_url}/v0/health")
+        r.raise_for_status()
+        return r.json()
+
+    def store(self, items: List[Dict[str, Any]]) -> Dict[str, Any]:
+        r = self._client.post(f"{self.base_url}/v0/store", json={"items": items})
+        r.raise_for_status()
+        return r.json()
+
+    def 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}/v0/search", json=payload)
+        r.raise_for_status()
+        return r.json()
+
+    def embed(self, texts: List[str]) -> Dict[str, Any]:
+        r = self._client.post(f"{self.base_url}/v0/embed", json={"texts": texts})
+        r.raise_for_status()
+        return r.json()
+
+

clients/typescript/contextforgeClient.ts

@@ -0,0 +1,54 @@
+export type MemoryItem = {
+  id: string;
+  namespace: string;
+  project_id: string;
+  kind: string;
+  text: string;
+  metadata?: Record<string, unknown>;
+};
+
+export class ContextForgeClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+
+  async health(): Promise<{ status: string }> {
+    const r = await fetch(`${this.baseUrl}/v0/health`);
+    if (!r.ok) throw new Error(`health failed: ${r.status}`);
+    return r.json();
+  }
+
+  async store(items: MemoryItem[]): Promise<{ stored: number }> {
+    const r = await fetch(`${this.baseUrl}/v0/store`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ items }),
+    });
+    if (!r.ok) throw new Error(`store failed: ${r.status}`);
+    return r.json();
+  }
+
+  async search(namespace: string, project_id: string, query: string, top_k = 5): Promise<{ results: MemoryItem[] }> {
+    const r = await fetch(`${this.baseUrl}/v0/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ namespace, project_id, query, top_k }),
+    });
+    if (!r.ok) throw new Error(`search failed: ${r.status}`);
+    return r.json();
+  }
+
+  async embed(texts: string[]): Promise<{ vectors: number[][] }> {
+    const r = await fetch(`${this.baseUrl}/v0/embed`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ texts }),
+    });
+    if (!r.ok) throw new Error(`embed failed: ${r.status}`);
+    return r.json();
+  }
+}
+
+

docs/adr/ADR-0001-product-scope-and-api-contracts.md

@@ -0,0 +1,28 @@
+### ADR-0001: Product Scope and API Contracts (ContextForge Memory)
+
+Status: Proposed
+
+#### Problem
+We need a small, reusable memory layer usable by Brainstorm and Cursor. It must be simple, versioned, and easy to self-host.
+
+#### Decision
+- Provide `/v0/health`, `/v0/store`, `/v0/search`, `/v0/embed`.
+- Use deterministic, hash-based embeddings initially; allow plug-in providers later.
+- Persist JSONL to disk by default; support alternative backends via env switches.
+- Namespacing: `namespace = vendor:project_id:env`; requests must include `namespace` and `project_id`.
+
+#### Consequences
+Positive: trivial to run, API-first, stable contract, multi-repo reuse.
+Negative: baseline embeddings are weak semantically; acceptable for phase 1.
+
+#### Versioning
+- Semantic version in OpenAPI; breaking changes bump path to `/v1`.
+
+#### Security & Limits
+- Start unauthenticated on localhost; add API key header later.
+- Soft limits: max text 64KB, batch store up to 100 items.
+
+#### Testing & Conformance
+- Contract tests run as part of CI; consumer repos can import and run the same tests.
+
+