Noosphere

A universal memory and knowledge layer for AI agents — structured enough for automation, readable enough for humans.

Noosphere started as an agent-authored wiki. It is now also a provider-agnostic memory system for recall orchestration, conflict handling, promotion/backfill, and local memory scheduling.

Agents can use Noosphere to store durable project knowledge, retrieve relevant context, synthesize articles from research, and promote frequently reused memories over time. Humans can browse and edit the same knowledge through a responsive web UI, export/import Markdown vaults, and sync with Obsidian.

Core Memory Features

What Noosphere Is For

Noosphere is useful when an AI system needs memory that is more durable and inspectable than a chat transcript.

Use it for:

• Agent memory — durable project facts, decisions, workflows, and learned patterns.
• Automatic recall — provider fan-out, ranking, deduplication, conflict resolution, and token-bounded prompt injection.
• Human-readable knowledge — wiki articles organized by topics, tags, relations, confidence, and status.
• Research synthesis — save answers or ingest external material into structured articles.
• Memory promotion — identify repeatedly useful ephemeral memories and promote them toward managed/curated knowledge.
• Historical backfill — synthesize older memory material into wiki articles with retryable jobs.
• Local automation — run memory maintenance jobs with the built-in scheduler.
• Obsidian workflows — export/import Markdown vaults and sync with an Obsidian-friendly structure.

Current Status

The universal memory MVP is feature-complete in the core Noosphere codebase.

Implemented memory modules:

• Provider abstraction for multiple recall sources.
• Noosphere article-backed memory provider.
• Hindsight HTTP recall provider.
• Recall orchestrator with concurrent provider fan-out.
• Composite ranking using relevance, confidence, recency, and curation.
• Cross-provider deduplication.
• Conflict detection and configurable resolution strategies.
• Context budget manager for prompt-safe recall blocks.
• Recall settings and conflict threshold configuration.
• Promotion candidate scoring and review lifecycle.
• Backfill/synthesis job lifecycle with retry support.
• Local scheduler baseline for memory jobs.
• Architecture documentation in docs/NOOSPHERE-MEMORY-ARCHITECTURE.md.

The OpenClaw plugin/skill bridge is implemented and ships in this repository at openclaw-noosphere-memory/. It provides explicit tools, optional auto-recall prompt injection, and memory corpus supplement wiring.

Frontpage	Logging

Feature Overview

For Agents and Integrations

• Write articles through REST API with API key authentication.
• Update articles with PATCH support and revision tracking.
• Ingest external sources into multiple structured articles in one request.
• Save synthesized answers as durable wiki articles.
• Search articles using PostgreSQL full-text search with filters.
• Traverse the wiki graph by topic, tag, and article relations.
• Run health checks for stale content, orphans, and missing metadata.
• Export/import Markdown vault archives.
• Use memory providers through a normalized MemoryProvider interface.
• Compose recall across Noosphere, Hindsight, and future providers.
• Generate prompt-ready recall blocks with token/result budgets.
• Bundled memory capture instructions — auto-injected guidance telling agents when/how to use noosphere_save; no manual policy files needed.
• Track promotion candidates from repeated recall use.
• Create backfill jobs to synthesize curated articles from historical material.
• Run scheduled memory jobs locally via npm run memory:scheduler.

For Humans

• Browse topics with unlimited-depth hierarchy.
• Read articles rendered from Markdown with code highlighting and tables.
• Edit articles in a Markdown editor with preview.
• Review revision history for changed articles.
• Soft-delete and restore articles from trash.
• Use tags for cross-cutting subjects.
• Upload images for embedded article media.
• Search the wiki by text, topic, tag, status, and confidence.
• View activity logs for create/update/delete/ingest/lint events.
• Manage API keys from the admin interface.
• Sync/export content for Obsidian and Markdown workflows.

Memory Architecture

Noosphere's memory layer normalizes multiple sources into a single result shape:

MemoryProvider
  → RecallOrchestrator
  → ranking
  → deduplication
  → conflict resolution
  → context budgeting
  → prompt injection text / inspection results

Core concepts:

• Providers return normalized MemoryResult objects.
• Curation levels are ephemeral → managed → curated.
• Composite score combines relevance, confidence, recency, and curation.
• Auto recall respects provider-level allowAutoRecall settings.
• Inspection recall queries enabled providers without auto-recall filtering.
• Deduplication collapses exact, canonical, or semantic overlap while preserving provenance.
• Conflict resolution can surface conflicts, suppress low-quality matches, or prefer recent/curated/highest-scoring results.
• Budgeting enforces prompt-safe token and result caps.
• Promotion identifies high-value recurring memories for review.
• Backfill turns approved or historical material into durable articles.

See the full implementation reference: docs/NOOSPHERE-MEMORY-ARCHITECTURE.md.

Advanced Memory Features

Wiki Model

Topic
├── Subtopic
│   ├── Article
│   └── Article
└── Subtopic
    └── Article

Articles can also have:

• tags
• source metadata
• confidence level: low | medium | high
• status: draft | reviewed | published
• revision history
• related article edges
• soft-delete state

Tech Stack

Getting Started

Prerequisites

• Docker + Docker Compose
• Node.js 22+ for local development

Setup

git clone https://github.com/SweetSophia/noosphere.git
cd noosphere

cp .env.example .env

# Generate secrets for .env
openssl rand -hex 32  # NEXTAUTH_SECRET
openssl rand -hex 32  # POSTGRES_PASSWORD

docker compose up -d
# Navigate to http://localhost:4400/wiki in your browser.

Create an Admin Account

docker compose exec app node scripts/create-admin.js

Then visit /wiki/login.

Official Docker Compose image

For the published image flow, copy noosphere.env.example next to the production Compose template and set strong secrets before starting:

cp noosphere.env.example .env
# edit .env: POSTGRES_PASSWORD, NEXTAUTH_SECRET, NOOSPHERE_ADMIN_PASSWORD, NOOSPHERE_BOOTSTRAP_API_KEY
docker compose -f docker-compose.noosphere.yml up -d

The production Compose template includes a one-shot init service. It waits for Postgres, applies Prisma migrations with docker/migrate-or-baseline.mjs, bootstraps the admin/API key/topics, and only then lets the app start. This prevents /api/health from reporting healthy before the schema exists.

Database ports differ by caller:

• App container: db:5432 on the internal Compose network.
• Host/local Prisma CLI: localhost:5433 when using the development Compose mapping.

Local Development

npm install
cp .env.example .env
# Update your local .env before starting:
# - DATABASE_URL should use the Postgres host port exposed by Docker Compose:
#   DATABASE_URL="postgresql://noosphere:YOUR_POSTGRES_PASSWORD@localhost:5433/noosphere"
# - Set NEXTAUTH_SECRET.
# - Set NEXTAUTH_URL="http://localhost:4400".
# - Set APP_URL="http://localhost:4400".
# - Set POSTGRES_PASSWORD.

docker compose up db -d
npx prisma migrate dev
npm run dev

Agent API Reference

Base URL: http://localhost:4400/api

Auth header:

Authorization: Bearer <api_key>

Articles

# Create article
POST /api/articles
# { title, slug, content, topicId, tags?, excerpt?, confidence?, status? }

# Update article
PATCH /api/articles/:id
# { title?, slug?, content?, topicId?, tags?, excerpt?, confidence?, status?, lastReviewed? }

# List/search articles
GET /api/articles?q=search&topic=slug&tag=tag&status=draft&confidence=high

# Get topics
GET /api/topics

# Human article route
GET /wiki/{topicSlug}/{articleSlug}

Ingest and Save

# Bulk ingest from an external source
POST /api/ingest
# { source: { type: "url", url: "...", title: "..." }, articles: [...], tags?: [...], authorName?: "AgentName" }

# Save a synthesized answer as an article
POST /api/answer
# { title, content, topicId, tags?, excerpt?, sourceQuery?, confidence?, status? }

Maintenance and Graph

# Wiki health check
POST /api/lint

# Activity log
GET /api/log?type=ingest&author=AgentName

# Wiki graph
GET /api/graph

# Service health
GET /api/health

Export and Import

# Export all articles as a Markdown vault zip
GET /api/export

# Import from a Markdown vault zip
POST /api/import
# multipart form fields: file, defaultTopicSlug?, overwrite?

Memory Module API

The memory layer is exposed in two ways:

TypeScript modules (for custom integrations)

Exposed from src/lib/memory via @/lib/memory:

import {
  createNoosphereProvider,
  createHindsightProvider,
  createRecallOrchestrator,
  createContextBudgetManager,
  createDeduplicator,
  createConflictResolver,
  scanForCandidates,
  recordRecall,
  createSynthesisJob,
  synthesize,
  createLocalMemoryScheduler,
} from "@/lib/memory";

Validation commands:

npm run test:memory
npm run test:scheduler
npx tsc --noEmit

HTTP API (for agents and OpenClaw plugins)

Base URL: http://localhost:4400/api
Auth: Authorization: Bearer <api_key>

Example recall request:

curl -s -X POST http://localhost:4400/api/memory/recall \
  -H "Authorization: Bearer noo_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "pk-pro database schema", "mode": "auto", "resultCap": 5}'

Example memory get:

curl -s -X POST http://localhost:4400/api/memory/get \
  -H "Authorization: Bearer noo_..." \
  -H "Content-Type: application/json" \
  -d '{"canonicalRef": "noosphere:article:abc123"}'

Example memory save:

curl -s -X POST http://localhost:4400/api/memory/save \
  -H "Authorization: Bearer noo_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "PK-PRO Database Schema", "content": "...", "topicId": "...", "tags": ["pk-pro"]}'

Web Routes

OpenClaw Integration

Noosphere ships an OpenClaw plugin at openclaw-noosphere-memory/ and an official local Docker Compose install path for OpenClaw users.

For the full setup, operations, troubleshooting, upgrade, and uninstall guide, see:

• docs/OPENCLAW-OFFICIAL-PLUGIN-SETUP.md

Quick install

On the machine running OpenClaw Gateway:

curl -fsSL https://raw.githubusercontent.com/SweetSophia/noosphere/master/install-openclaw.sh | bash
openclaw noosphere doctor
openclaw noosphere status

Defaults are local-only and safe for personal OpenClaw deployments:

• Noosphere URL: http://127.0.0.1:6578
• Runtime directory: ~/.noosphere
• OpenClaw secret file: ~/.openclaw/secrets/noosphere-memory.json
• Docker image: ghcr.io/sweetsophia/noosphere:latest

Plugin capabilities

Explicit tools:

Auto-injection:

When autoRecall: true, OpenClaw permits hook injection, and recall returns non-empty prompt text, the plugin's before_prompt_build hook can inject:

1. <noosphere_memory_capture> — guidance telling agents when/how to call noosphere_save.
2. <noosphere_auto_recall> — ranked, deduplicated, conflict-resolved recall results within budget.

Important: OpenClaw requires this hook permission before any prompt text can be injected:

{
  "plugins": {
    "entries": {
      "noosphere-memory": {
        "hooks": {
          "allowPromptInjection": true
        }
      }
    }
  }
}

Without hooks.allowPromptInjection: true, explicit tools still work, but auto-recall and memory capture instructions will not appear in agent context.

Memory corpus supplement:

The plugin registers a Noosphere memory corpus supplement so OpenClaw shared memory flows can query Noosphere content through the unified memory interface.

OpenClaw CLI helpers:

The plugin registers openclaw noosphere ... helpers for status, diagnostics, logs guidance, setup guidance, and upgrade guidance. See the setup guide for the canonical command reference.

Safety properties

• Default Docker Compose binding is localhost-only: 127.0.0.1:6578.
• PostgreSQL stays internal to the production Compose network.
• API keys are permission-scoped; READ/WRITE/ADMIN are used for different actions.
• Secrets are stored outside the repo in OpenClaw secret files and ~/.noosphere/.env.
• Auto-recall fails open when Noosphere is unreachable.
• The installer enables broad prompt injection by default (autoRecall: true, allowPromptInjection: true, no agent/chat allowlist); restrict it with enabledAgents/allowedChatTypes if needed.
• noosphere_save creates draft candidates only.

Environment Variables

Deployment

# Build and start
docker compose up -d --build

# Run production migrations after first deploy or schema changes
docker compose exec app node node_modules/prisma/build/index.js migrate deploy --schema prisma/schema.prisma

# View logs
docker compose logs -f app

Documentation

• docs/OPENCLAW-OFFICIAL-PLUGIN-SETUP.md — official OpenClaw install, operations, upgrade, and troubleshooting guide
• docs/OPENCLAW-OFFICIAL-PLUGIN-DEVELOPMENT-PLAN.md — productization plan and release checklist
• docs/NOOSPHERE-MEMORY-ARCHITECTURE.md — memory architecture and configuration model
• docs/NOOSPHERE-SKILL.md — agent-facing wiki skill reference
• docs/OBSIDIAN-SYNC-SPEC.md — Obsidian sync design
• docs/OBSIDIAN-SYNC-REVIEW.md — Obsidian sync review notes
• docs/SECURITY-AUDIT-2026-04-16.md — security audit notes

License

MIT — see LICENSE