feat: framework examples, Docker standalone, ChatGPT plugin (#70, #71, #74)

#70 — Five Python integration examples:
  - simple_chatbot.py — complete chatbot with ConversationMemory
  - openai_tools.py — OpenAI function calling with MemForge tools
  - claude_tools.py — Anthropic tool use with MemForge tools
  - langchain_memory.py — LangChain conversation memory backend
  - quickstart.py — Python equivalent of the TypeScript quickstart

#71 — Docker standalone single-container:
  - Dockerfile.standalone with embedded PostgreSQL
  - docker run -p 3333:3333 salishforge/memforge:standalone
  - No Docker Compose needed for evaluation/development

#74 — ChatGPT plugin manifest:
  - public/ai-plugin.json pointing to /api/spec.json
  - Enables MemForge as a ChatGPT plugin

Closes #70, closes #71, closes #74

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Artificium

Dockerfile.standalone

@@ -0,0 +1,35 @@
+FROM postgres:16-alpine
+
+# Install Node.js 22 and build tools
+RUN apk add --no-cache nodejs npm curl
+
+# pgvector — build from source (not in Alpine package repos for pg 16)
+RUN apk add --no-cache postgresql16-dev git build-base \
+    && git clone --branch v0.8.0 --depth 1 https://github.com/pgvector/pgvector.git /tmp/pgvector \
+    && cd /tmp/pgvector && make && make install \
+    && rm -rf /tmp/pgvector \
+    && apk del git build-base
+
+# pg_trgm is bundled with PostgreSQL — just enable it via schema
+
+# Copy MemForge application
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist/ ./dist/
+COPY schema/ ./schema/
+
+# Standalone entrypoint
+COPY docker-entrypoint-standalone.sh /docker-entrypoint-standalone.sh
+RUN chmod +x /docker-entrypoint-standalone.sh
+
+EXPOSE 3333
+
+# Defaults tuned for single-container use with local embeddings
+ENV EMBEDDING_PROVIDER=local
+ENV CONSOLIDATION_INNER_BATCH_SIZE=1
+ENV DATABASE_URL=postgresql://postgres@localhost/memforge
+ENV PORT=3333
+ENV LOG_LEVEL=info
+
+ENTRYPOINT ["/docker-entrypoint-standalone.sh"]

docker-entrypoint-standalone.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+set -e
+
+# ── 1. Initialise PostgreSQL data directory if needed ────────────────────────
+PGDATA="${PGDATA:-/var/lib/postgresql/data}"
+
+if [ ! -f "$PGDATA/PG_VERSION" ]; then
+    echo "[standalone] Initialising PostgreSQL data directory..."
+    su-exec postgres initdb -D "$PGDATA" --encoding=UTF8 --auth=trust
+fi
+
+# ── 2. Start PostgreSQL in the background ────────────────────────────────────
+echo "[standalone] Starting PostgreSQL..."
+su-exec postgres pg_ctl -D "$PGDATA" -l "$PGDATA/pg.log" start -w \
+    -o "-c listen_addresses=localhost -c max_connections=50"
+
+# ── 3. Create database and apply schema ──────────────────────────────────────
+echo "[standalone] Creating database..."
+su-exec postgres createdb memforge 2>/dev/null || true
+
+echo "[standalone] Applying schema..."
+su-exec postgres psql -d memforge -f /app/schema/schema.sql 2>/dev/null || true
+
+# Apply any available migrations in version order
+for f in $(ls /app/schema/migration-*.sql 2>/dev/null | sort); do
+    echo "[standalone] Applying migration: $f"
+    su-exec postgres psql -d memforge -f "$f" 2>/dev/null || true
+done
+
+# ── 4. Verify extensions ─────────────────────────────────────────────────────
+echo "[standalone] Verifying extensions..."
+su-exec postgres psql -d memforge -c "CREATE EXTENSION IF NOT EXISTS vector;" 2>/dev/null || true
+su-exec postgres psql -d memforge -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" 2>/dev/null || true
+
+# ── 5. Start MemForge ────────────────────────────────────────────────────────
+echo "[standalone] Starting MemForge on port ${PORT:-3333}..."
+exec node /app/dist/server.js

examples/claude_tools.py

@@ -0,0 +1,90 @@
+"""Anthropic Claude tool use with MemForge memory tools.
+
+Demonstrates tool definitions, handling tool_use blocks, and routing to MemForge.
+
+Run:
+    pip install memforge anthropic
+    ANTHROPIC_API_KEY=... python examples/claude_tools.py
+"""
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+from memforge import MemForgeClient
+from memforge.tools import anthropic_tools
+
+AGENT_ID = "claude-tools-demo"
+SYSTEM_PROMPT = (
+    "You are a helpful assistant with access to a persistent memory store. "
+    "Use memforge_query to recall knowledge before answering. "
+    "Use memforge_add to store important new facts."
+)
+
+
+async def dispatch_tool(client: MemForgeClient, name: str, args: dict[str, Any]) -> str:
+    """Route an Anthropic tool_use block to the MemForge client."""
+    try:
+        if name == "memforge_add":
+            r = await client.add(args["agent_id"], args["content"],
+                                 outcome_type=args.get("outcome_type", "neutral"))
+            return json.dumps({"id": r.id})
+        if name == "memforge_query":
+            results = await client.query(args["agent_id"], q=args["q"],
+                                         limit=args.get("limit", 10), mode=args.get("mode"))
+            return json.dumps([{"content": r.summary or r.content, "rank": r.rank} for r in results])
+        if name == "memforge_consolidate":
+            r = await client.consolidate(args["agent_id"], args.get("mode"))
+            return json.dumps({"warm_rows_created": r.warm_rows_created})
+        if name == "memforge_active_recall":
+            r = await client.active_recall(args["agent_id"], args["context"], args.get("limit", 5))
+            return json.dumps(r)
+        if name == "memforge_stats":
+            s = await client.stats(args["agent_id"])
+            return json.dumps({"hot": s.hot_count, "warm": s.warm_count})
+        return json.dumps({"error": f"Unknown tool: {name}"})
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+async def run_agent_turn(client: MemForgeClient, ac: Any, user_message: str) -> str:
+    """Run one agentic turn, looping over tool calls until Claude returns text."""
+    tools = anthropic_tools()
+    messages: list[dict[str, Any]] = [{"role": "user", "content": user_message}]
+    while True:
+        resp = await ac.messages.create(model="claude-haiku-4-5", max_tokens=1024,
+                                         system=SYSTEM_PROMPT, tools=tools, messages=messages)
+        messages.append({"role": "assistant", "content": resp.content})
+        tool_uses = [b for b in resp.content if b.type == "tool_use"]
+        if not tool_uses:
+            texts = [b for b in resp.content if b.type == "text"]
+            return texts[0].text if texts else ""
+        results = []
+        for b in tool_uses:
+            results.append({"type": "tool_result", "tool_use_id": b.id,
+                            "content": await dispatch_tool(client, b.name, b.input)})
+        messages.append({"role": "user", "content": results})
+
+
+async def main() -> None:
+    try:
+        import anthropic
+    except ImportError:
+        print("Install anthropic: pip install anthropic", file=sys.stderr); sys.exit(1)
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        print("Set ANTHROPIC_API_KEY", file=sys.stderr); sys.exit(1)
+
+    ac = anthropic.AsyncAnthropic()
+    async with MemForgeClient() as client:
+        await client.add(AGENT_ID, "Our API rate limit is 1000 requests per minute")
+        await client.add(AGENT_ID, "Database backups run daily at 03:00 UTC")
+        await client.consolidate(AGENT_ID)
+        query = "What infrastructure constraints should I know about?"
+        print(f"User: {query}\n")
+        print(f"Claude: {await run_agent_turn(client, ac, query)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/langchain_memory.py

@@ -0,0 +1,126 @@
+"""LangChain integration using MemForge as conversation memory backend.
+
+Demonstrates:
+  - Wrapping ConversationMemory as a LangChain BaseChatMemory subclass
+  - Injecting MemForge context into the LangChain chain via load_memory_variables
+  - Storing LangChain exchanges back to MemForge via save_context
+  - Drop-in replacement for ConversationBufferMemory
+
+Run:
+    pip install memforge langchain langchain-openai
+    OPENAI_API_KEY=... python examples/langchain_memory.py
+"""
+
+import asyncio
+import os
+import sys
+from typing import Any
+
+AGENT_ID = "langchain-demo"
+
+
+def build_memforge_memory(agent_id: str) -> "MemForgeMemory":
+    """Create a LangChain-compatible memory backed by MemForge."""
+    try:
+        from langchain.memory.chat_memory import BaseChatMemory
+        from langchain.schema import BaseMessage, HumanMessage, AIMessage
+    except ImportError:
+        print("Install langchain: pip install langchain", file=sys.stderr)
+        sys.exit(1)
+
+    from memforge import ConversationMemory
+
+    class MemForgeMemory(BaseChatMemory):
+        """LangChain memory adapter backed by MemForge persistent storage.
+
+        Implements the minimal BaseChatMemory interface so it can be passed
+        directly to any LangChain chain that accepts a ``memory`` parameter.
+        """
+
+        memory_key: str = "history"
+        agent_id: str = "langchain-agent"
+        _memforge: Any = None  # ConversationMemory, set via model_post_init
+
+        class Config:
+            arbitrary_types_allowed = True
+
+        def __init__(self, agent_id: str = "langchain-agent", **kwargs: Any) -> None:
+            super().__init__(**kwargs)
+            object.__setattr__(self, "agent_id", agent_id)
+            object.__setattr__(self, "_memforge", ConversationMemory(agent_id=agent_id))
+
+        @property
+        def memory_variables(self) -> list[str]:
+            return [self.memory_key]
+
+        def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+            """Retrieve relevant MemForge context synchronously for LangChain."""
+            human_input = inputs.get("input", inputs.get("human_input", ""))
+            context = asyncio.get_event_loop().run_until_complete(
+                self._memforge.get_context(human_input, max_tokens=1500)
+            )
+            return {self.memory_key: context}
+
+        def save_context(self, inputs: dict[str, Any], outputs: dict[str, str]) -> None:
+            """Persist the latest exchange to MemForge."""
+            human = inputs.get("input", inputs.get("human_input", ""))
+            ai = outputs.get("output", outputs.get("response", ""))
+            loop = asyncio.get_event_loop()
+            if human:
+                loop.run_until_complete(self._memforge.add_turn("user", human))
+            if ai:
+                loop.run_until_complete(self._memforge.add_turn("assistant", ai))
+
+        def clear(self) -> None:
+            """No-op: MemForge persists across sessions by design."""
+
+    return MemForgeMemory(agent_id=agent_id)  # type: ignore[return-value]
+
+
+async def main() -> None:
+    try:
+        from langchain_openai import ChatOpenAI
+        from langchain.chains import ConversationChain
+        from langchain.prompts import PromptTemplate
+    except ImportError:
+        print("Install: pip install langchain langchain-openai", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY environment variable", file=sys.stderr)
+        sys.exit(1)
+
+    memory = build_memforge_memory(AGENT_ID)
+
+    chain = ConversationChain(
+        llm=ChatOpenAI(model="gpt-4o-mini"),
+        memory=memory,
+        prompt=PromptTemplate(
+            input_variables=["history", "input"],
+            template=(
+                "You are a helpful assistant. Past context:\n{history}\n\n"
+                "Human: {input}\nAssistant:"
+            ),
+        ),
+        verbose=False,
+    )
+
+    exchanges = [
+        "My name is Alex and I prefer concise answers.",
+        "What's a good way to structure a Python project?",
+        "Do you remember my preference from earlier?",
+    ]
+
+    for user_msg in exchanges:
+        print(f"Human: {user_msg}")
+        response = chain.predict(input=user_msg)
+        print(f"Assistant: {response}\n")
+
+    print("[Memory] Consolidating session...")
+    await memory._memforge.end_session()
+    await memory._memforge.close()
+    print("[Memory] Done.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/openai_tools.py

@@ -0,0 +1,90 @@
+"""OpenAI function calling with MemForge memory tools.
+
+Demonstrates tool definitions, handling tool_calls, and routing to MemForge.
+
+Run:
+    pip install memforge openai
+    OPENAI_API_KEY=... python examples/openai_tools.py
+"""
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+from memforge import MemForgeClient
+from memforge.tools import openai_tools
+
+AGENT_ID = "openai-tools-demo"
+SYSTEM_PROMPT = (
+    "You are a helpful assistant with access to a persistent memory store. "
+    "Use memforge_query to recall knowledge before answering. "
+    "Use memforge_add to store important new information."
+)
+
+
+async def dispatch_tool(client: MemForgeClient, name: str, args: dict[str, Any]) -> str:
+    """Route an OpenAI tool_call to the MemForge client."""
+    try:
+        if name == "memforge_add":
+            r = await client.add(args["agent_id"], args["content"],
+                                 outcome_type=args.get("outcome_type", "neutral"))
+            return json.dumps({"id": r.id})
+        if name == "memforge_query":
+            results = await client.query(args["agent_id"], q=args["q"],
+                                         limit=args.get("limit", 10), mode=args.get("mode"))
+            return json.dumps([{"content": r.summary or r.content, "rank": r.rank} for r in results])
+        if name == "memforge_consolidate":
+            r = await client.consolidate(args["agent_id"], args.get("mode"))
+            return json.dumps({"warm_rows_created": r.warm_rows_created})
+        if name == "memforge_active_recall":
+            r = await client.active_recall(args["agent_id"], args["context"], args.get("limit", 5))
+            return json.dumps(r)
+        if name == "memforge_stats":
+            s = await client.stats(args["agent_id"])
+            return json.dumps({"hot": s.hot_count, "warm": s.warm_count})
+        return json.dumps({"error": f"Unknown tool: {name}"})
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+async def run_agent_turn(client: MemForgeClient, oc: Any, user_message: str) -> str:
+    """Run one agentic turn, looping over tool calls until the model returns text."""
+    tools = openai_tools()
+    messages: list[dict[str, Any]] = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user_message},
+    ]
+    while True:
+        resp = await oc.chat.completions.create(model="gpt-4o-mini", messages=messages,
+                                                 tools=tools, tool_choice="auto")
+        msg = resp.choices[0].message
+        messages.append(msg.model_dump(exclude_none=True))
+        if not msg.tool_calls:
+            return msg.content or ""
+        for tc in msg.tool_calls:
+            result = await dispatch_tool(client, tc.function.name, json.loads(tc.function.arguments))
+            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
+
+
+async def main() -> None:
+    try:
+        import openai
+    except ImportError:
+        print("Install openai: pip install openai", file=sys.stderr); sys.exit(1)
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY", file=sys.stderr); sys.exit(1)
+
+    oc = openai.AsyncOpenAI()
+    async with MemForgeClient() as client:
+        await client.add(AGENT_ID, "The team deploys every Tuesday at 14:00 UTC")
+        await client.add(AGENT_ID, "Redis cache TTL is 5 minutes for hot paths")
+        await client.consolidate(AGENT_ID)
+        query = "When do we deploy and what's our cache TTL?"
+        print(f"User: {query}\n")
+        print(f"Assistant: {await run_agent_turn(client, oc, query)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())