open-cognition 0.1.1__tar.gz

open_cognition-0.1.1/.env.example

@@ -0,0 +1,5 @@
+SURREAL_URL=ws://localhost:8000/rpc
+SURREAL_USER=root
+SURREAL_PASSWORD=root
+SURREAL_NAMESPACE=open-cognition
+SURREAL_DATABASE=test

open_cognition-0.1.1/.github/workflows/create-tag.yml

@@ -0,0 +1,42 @@
+name: Create Release Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: 'Type "yes" to confirm tag creation'
+        required: true
+        type: string
+
+jobs:
+  create-tag:
+    runs-on: ubuntu-latest
+    if: github.event.inputs.confirm == 'yes'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$VERSION" >> $GITHUB_OUTPUT
+          echo "Detected version: $VERSION"
+
+      - name: Check if tag already exists
+        run: |
+          if git rev-parse "${{ steps.version.outputs.tag }}" >/dev/null 2>&1; then
+            echo "Tag ${{ steps.version.outputs.tag }} already exists!"
+            exit 1
+          fi
+
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.tag }}" -m "Release ${{ steps.version.outputs.tag }}"
+          git push origin "${{ steps.version.outputs.tag }}"
+          echo "Created and pushed tag ${{ steps.version.outputs.tag }}"

open_cognition-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish --token "$PYPI_TOKEN"

open_cognition-0.1.1/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment
+.env
+
+# Project docs (internal)
+MVP.md
+VISION.md

open_cognition-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

open_cognition-0.1.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: open-cognition
+Version: 0.1.1
+Summary: AI-powered learning system with spaced repetition
+Requires-Python: >=3.13
+Requires-Dist: fastapi
+Requires-Dist: fastmcp
+Requires-Dist: jinja2
+Requires-Dist: loguru
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: surreal-basics>=0.3.0
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+# open-cognition
+
+AI-powered learning system with spaced repetition. Study with LLMs, capture knowledge, review with science-backed methods.
+
+## The Problem
+
+When you study with AI (Claude, ChatGPT, etc.), the knowledge gets lost. You learn in one place, take notes in another, create flashcards in a third, and review in isolation. There's no system connecting the dots.
+
+## How it Works
+
+open-cognition bridges the gap between AI-assisted learning and retention:
+
+1. **Study with your LLM** — Claude acts as your Socratic sparring partner via MCP
+2. **Capture outputs** — flashcards, summaries, resources, and artifacts are saved automatically
+3. **Organize in a knowledge graph** — topics and subtopics you control
+4. **Review with spaced repetition** — SM-2 algorithm (same foundation as Anki)
+5. **Deepen with Feynman technique** — structured sessions that identify and close knowledge gaps
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+That's it. No database server required — open-cognition uses an embedded local database file by default. Your data stays on your machine.
+
+### Install and Run
+
+```bash
+# Run directly (no clone needed)
+uvx open-cognition serve
+```
+
+Open http://localhost:8080 and start learning.
+
+### Using with Claude Desktop
+
+This is where open-cognition shines. Connect it to Claude Desktop and get a learning partner that knows your knowledge graph.
+
+#### 1. Set up the MCP Server
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "open-cognition": {
+      "command": "uvx",
+      "args": ["open-cognition", "mcp"]
+    }
+  }
+}
+```
+
+That's it — `uvx` handles installation and dependencies automatically.
+
+#### 2. Add the Skill
+
+Download [SKILL.md](https://raw.githubusercontent.com/lfnovo/open-cognition/main/SKILL.md) and add it to your Claude Desktop skills, or include it in your project's `.claude/skills/` folder.
+
+The skill instructs Claude to:
+- Be a **Socratic sparring partner** during study sessions — not a lecturer
+- Use the **Feynman technique** to identify and close knowledge gaps
+- Create high-quality flashcards following strict rules (atomic, active recall, concise)
+- Never create topics or cards without your approval
+- Track your doubts and struggling cards
+
+#### 3. Start Learning
+
+Talk to Claude naturally:
+
+- *"Let's study Transformers"* → starts a session, loads your existing knowledge
+- *"Create flashcards from what we discussed"* → proposes cards for your approval
+- *"Let's do a Feynman session on Attention"* → structured gap-finding protocol
+- *"What doubts do I have open?"* → reviews pending questions
+- *"Which cards am I struggling with?"* → identifies weak spots
+
+## Features
+
+### Web UI
+
+- **Dashboard** — due cards count, struggling cards, quick actions
+- **Topics** — create, edit, delete, hierarchical subtopics
+- **Review session** — flashcard review with SM-2, quality buttons, progress tracking
+- **Artifacts** — markdown + mermaid rendering in modal viewer
+- **Resources** — links, PDFs, videos organized by topic
+- **Doubts** — capture questions during review, work them later with the LLM
+- **Struggling cards** — analytics on most-errored flashcards
+- **Copyable IDs** — click any entity ID to copy (e.g., `topic:abc123`) for LLM reference
+
+### MCP Tools (18 tools)
+
+| Category | Tools |
+|----------|-------|
+| Topics | get_topics, create_topic, update_topic, relate_topics |
+| Flashcards | get_flashcards, get_due_flashcards, create_flashcard, create_flashcards_batch, review_flashcard, get_struggling_cards |
+| Resources | get_resources, create_resource |
+| Artifacts | get_artifacts, create_artifact |
+| Doubts | get_doubts, create_doubt, resolve_doubt |
+| Sessions | start_session, end_session, get_session_logs |
+
+### Spaced Repetition (SM-2)
+
+The same algorithm behind Anki. Cards you answer correctly get longer intervals; cards you miss reset to 1 day. The ease factor adapts per card — easy cards space out faster, hard cards stay frequent.
+
+See [docs/sm2.md](docs/sm2.md) for the full algorithm with formulas and examples.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OC_HOST` | `0.0.0.0` | Web server host |
+| `OC_PORT` | `8080` | Web server port |
+| `OC_DATA_DIR` | `~/.open-cognition` | Data directory |
+| `SURREAL_URL` | — | SurrealDB connection URL (optional — uses embedded DB if not set) |
+| `SURREAL_USER` | `root` | SurrealDB username |
+| `SURREAL_PASSWORD` | `root` | SurrealDB password |
+| `SURREAL_NAMESPACE` | `open-cognition` | SurrealDB namespace |
+| `SURREAL_DATABASE` | `test` | SurrealDB database |
+
+You can set these in a `.env` file or as environment variables.
+
+### External SurrealDB (optional)
+
+By default, open-cognition stores everything in a local file. If you prefer a standalone SurrealDB server (for multi-device access, backups, or production):
+
+```bash
+# Via Docker
+docker compose up -d
+
+# Or point to your existing instance
+export SURREAL_URL=ws://localhost:8000/rpc
+```
+
+## CLI
+
+```bash
+uvx open-cognition serve [--host HOST] [--port PORT]   # Start the web app
+uvx open-cognition mcp                                  # Start the MCP server
+uvx open-cognition --version                            # Show version
+uvx open-cognition --help                               # Show help
+```
+
+## Architecture
+
+```
+Claude (LLM) ──► MCP Tools ──┐
+                              ├──► Services ──► Repositories ──► SurrealDB
+Web UI (HTMX) ──► API Routes ┘
+```
+
+MCP tools and API routes share the same services layer. The LLM and the web UI see the same data.
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Development
+
+```bash
+git clone https://github.com/lfnovo/open-cognition.git
+cd open-cognition
+uv sync
+open-cognition serve
+```
+
+Run tests:
+```bash
+uv run pytest
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — layers, data model, graph relations
+- [Concepts](docs/concepts.md) — topics, flashcards, resources, artifacts, sessions, doubts
+- [SM-2 Algorithm](docs/sm2.md) — spaced repetition formulas and examples
+- [API Reference](docs/api.md) — REST endpoints
+- [MCP Tools](docs/mcp-tools.md) — tools for LLM integration
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | Python + FastAPI |
+| Database | SurrealDB (embedded file or server) |
+| Frontend | HTMX + Jinja2 + Tailwind CSS |
+| MCP | FastMCP |
+| LLM | Claude (via skill + MCP) |
+
+## License
+
+MIT

open_cognition-0.1.1/README.md

@@ -0,0 +1,191 @@
+# open-cognition
+
+AI-powered learning system with spaced repetition. Study with LLMs, capture knowledge, review with science-backed methods.
+
+## The Problem
+
+When you study with AI (Claude, ChatGPT, etc.), the knowledge gets lost. You learn in one place, take notes in another, create flashcards in a third, and review in isolation. There's no system connecting the dots.
+
+## How it Works
+
+open-cognition bridges the gap between AI-assisted learning and retention:
+
+1. **Study with your LLM** — Claude acts as your Socratic sparring partner via MCP
+2. **Capture outputs** — flashcards, summaries, resources, and artifacts are saved automatically
+3. **Organize in a knowledge graph** — topics and subtopics you control
+4. **Review with spaced repetition** — SM-2 algorithm (same foundation as Anki)
+5. **Deepen with Feynman technique** — structured sessions that identify and close knowledge gaps
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+That's it. No database server required — open-cognition uses an embedded local database file by default. Your data stays on your machine.
+
+### Install and Run
+
+```bash
+# Run directly (no clone needed)
+uvx open-cognition serve
+```
+
+Open http://localhost:8080 and start learning.
+
+### Using with Claude Desktop
+
+This is where open-cognition shines. Connect it to Claude Desktop and get a learning partner that knows your knowledge graph.
+
+#### 1. Set up the MCP Server
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "open-cognition": {
+      "command": "uvx",
+      "args": ["open-cognition", "mcp"]
+    }
+  }
+}
+```
+
+That's it — `uvx` handles installation and dependencies automatically.
+
+#### 2. Add the Skill
+
+Download [SKILL.md](https://raw.githubusercontent.com/lfnovo/open-cognition/main/SKILL.md) and add it to your Claude Desktop skills, or include it in your project's `.claude/skills/` folder.
+
+The skill instructs Claude to:
+- Be a **Socratic sparring partner** during study sessions — not a lecturer
+- Use the **Feynman technique** to identify and close knowledge gaps
+- Create high-quality flashcards following strict rules (atomic, active recall, concise)
+- Never create topics or cards without your approval
+- Track your doubts and struggling cards
+
+#### 3. Start Learning
+
+Talk to Claude naturally:
+
+- *"Let's study Transformers"* → starts a session, loads your existing knowledge
+- *"Create flashcards from what we discussed"* → proposes cards for your approval
+- *"Let's do a Feynman session on Attention"* → structured gap-finding protocol
+- *"What doubts do I have open?"* → reviews pending questions
+- *"Which cards am I struggling with?"* → identifies weak spots
+
+## Features
+
+### Web UI
+
+- **Dashboard** — due cards count, struggling cards, quick actions
+- **Topics** — create, edit, delete, hierarchical subtopics
+- **Review session** — flashcard review with SM-2, quality buttons, progress tracking
+- **Artifacts** — markdown + mermaid rendering in modal viewer
+- **Resources** — links, PDFs, videos organized by topic
+- **Doubts** — capture questions during review, work them later with the LLM
+- **Struggling cards** — analytics on most-errored flashcards
+- **Copyable IDs** — click any entity ID to copy (e.g., `topic:abc123`) for LLM reference
+
+### MCP Tools (18 tools)
+
+| Category | Tools |
+|----------|-------|
+| Topics | get_topics, create_topic, update_topic, relate_topics |
+| Flashcards | get_flashcards, get_due_flashcards, create_flashcard, create_flashcards_batch, review_flashcard, get_struggling_cards |
+| Resources | get_resources, create_resource |
+| Artifacts | get_artifacts, create_artifact |
+| Doubts | get_doubts, create_doubt, resolve_doubt |
+| Sessions | start_session, end_session, get_session_logs |
+
+### Spaced Repetition (SM-2)
+
+The same algorithm behind Anki. Cards you answer correctly get longer intervals; cards you miss reset to 1 day. The ease factor adapts per card — easy cards space out faster, hard cards stay frequent.
+
+See [docs/sm2.md](docs/sm2.md) for the full algorithm with formulas and examples.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OC_HOST` | `0.0.0.0` | Web server host |
+| `OC_PORT` | `8080` | Web server port |
+| `OC_DATA_DIR` | `~/.open-cognition` | Data directory |
+| `SURREAL_URL` | — | SurrealDB connection URL (optional — uses embedded DB if not set) |
+| `SURREAL_USER` | `root` | SurrealDB username |
+| `SURREAL_PASSWORD` | `root` | SurrealDB password |
+| `SURREAL_NAMESPACE` | `open-cognition` | SurrealDB namespace |
+| `SURREAL_DATABASE` | `test` | SurrealDB database |
+
+You can set these in a `.env` file or as environment variables.
+
+### External SurrealDB (optional)
+
+By default, open-cognition stores everything in a local file. If you prefer a standalone SurrealDB server (for multi-device access, backups, or production):
+
+```bash
+# Via Docker
+docker compose up -d
+
+# Or point to your existing instance
+export SURREAL_URL=ws://localhost:8000/rpc
+```
+
+## CLI
+
+```bash
+uvx open-cognition serve [--host HOST] [--port PORT]   # Start the web app
+uvx open-cognition mcp                                  # Start the MCP server
+uvx open-cognition --version                            # Show version
+uvx open-cognition --help                               # Show help
+```
+
+## Architecture
+
+```
+Claude (LLM) ──► MCP Tools ──┐
+                              ├──► Services ──► Repositories ──► SurrealDB
+Web UI (HTMX) ──► API Routes ┘
+```
+
+MCP tools and API routes share the same services layer. The LLM and the web UI see the same data.
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Development
+
+```bash
+git clone https://github.com/lfnovo/open-cognition.git
+cd open-cognition
+uv sync
+open-cognition serve
+```
+
+Run tests:
+```bash
+uv run pytest
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — layers, data model, graph relations
+- [Concepts](docs/concepts.md) — topics, flashcards, resources, artifacts, sessions, doubts
+- [SM-2 Algorithm](docs/sm2.md) — spaced repetition formulas and examples
+- [API Reference](docs/api.md) — REST endpoints
+- [MCP Tools](docs/mcp-tools.md) — tools for LLM integration
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | Python + FastAPI |
+| Database | SurrealDB (embedded file or server) |
+| Frontend | HTMX + Jinja2 + Tailwind CSS |
+| MCP | FastMCP |
+| LLM | Claude (via skill + MCP) |
+
+## License
+
+MIT