Pensieve Docs

Writing Your First Article with Pensieve

tutorialgetting-startedpipeline

Writing Your First Article with Pensieve

This tutorial walks you through writing a complete article with Pensieve from start to finish. By the end you will have a finished draft that has been researched, outlined, written, reviewed, and polished by a team of purpose-built AI agents.

Time: ~20 minutes setup + pipeline runtime (varies by LLM and stage configuration)

Prerequisites:

  • Pensieve is installed and running (Local Setup or Docker Compose)
  • You have a valid OPENAI_API_KEY in your .env file
  • The frontend is open at http://localhost:3000 (or http://localhost:5173 for the Vite dev server)

Step 1: Create a Workspace

A workspace is your writing environment — it holds your identity, your topic library, and all your projects. Workspaces are completely independent from each other, so you can have one for technical writing, one for creative fiction, and so on.

  1. Open the Pensieve frontend.
  2. Click New Workspace in the sidebar.
  3. Enter a name (e.g., my-blog) and click Create.

Pensieve creates a directory at workspaces/my-blog/ with a default config.yaml, an empty identity/ folder, and an empty topics/ folder.

Step 2: Set Up Your Author Identity

Your identity tells every agent who you are. Agents inject this context into their prompts, so the output will reflect your voice rather than a generic one.

  1. In the sidebar, select your workspace and click Memory.
  2. Open the Identity tab.
  3. Edit voice.md — describe your tone, style, and the kinds of things you write about. For example:
   I write clear, practical technical articles aimed at developers.
   I prefer short paragraphs, concrete examples, and minimal jargon.
   I avoid hype and prefer measured, accurate language.
  1. Optionally edit style_guide.md to add formatting preferences (heading style, use of bullet points, preferred Oxford comma usage, etc.) and author_bio.md for a short bio that agents can reference.

Tip: You can update these files any time. Changes take effect on the next project you start.

Step 3: Start a Project

A project is a single piece of writing. Each project runs through its own pipeline and produces its own set of artifacts.

  1. In the sidebar, click New Project under your workspace.
  2. Enter a topic for your article. Be descriptive but concise — this becomes the seed for the Topic Refinement agent. For example:

“How LangChain agents use tool calling to take multi-step actions”

  1. Optionally select a preset from the dropdown. For a first run, minimal is a good choice — it only runs Topic Refinement and First Draft, so you can see results quickly.
  2. Click Create.

Pensieve creates a project directory at workspaces/my-blog/projects/<project-id>/ and writes your topic as brief.md.

Step 4: Run the Pipeline

You are now on the Project Detail screen. The pipeline panel on the right shows the 10 stages.

Execute Next

Click Execute Next to run the first stage (Topic Refinement). Watch the agent panel on the left for live output — you can see the agent’s reasoning, tool calls, and the text it writes.

When the stage completes, the artifact (topic_brief.md) appears in the Artifacts panel. Open it to review what the agent produced.

Click Execute Next again to run the next stage, and so on. This gives you a chance to review each artifact before proceeding.

Execute All

If you trust the pipeline, click Execute All to run every remaining stage without stopping. The pipeline streams output in real time and stops when all stages are done (or when it reaches a stage that needs your input).

Pause and Resume

Click Pause at any time to stop after the current stage finishes. You can then review artifacts, edit them directly in the editor, or adjust configuration before resuming.

Step 5: Review the Artifacts

As the pipeline runs, it produces artifacts that build on each other:

Artifact Produced by What it contains
topic_brief.md Topic Refinement Refined topic, angle, target audience, key questions
research_notes.md Research Facts, sources, and relevant context gathered from the web
outline.md Outliner Section-by-section structure for the article
draft_v1.md First Draft Full first draft of the article
content_review.md Content Reviewer Feedback on structure, coverage, and clarity
fact_check.md Fact Checker Identified claims and their verification status
style_review.md Style Reviewer Feedback on tone, style, and consistency with your voice
draft_v2.md Reviser Revised draft incorporating all review feedback
final.md Polisher Final polished version ready to publish
consistency_report.md Consistency Checker Flagged inconsistencies between the draft and your identity/prior work

Click any artifact in the panel to read it. You can also edit artifacts directly — changes are saved automatically and picked up by downstream agents.

Step 6: Publish Your Article

When the pipeline completes, final.md contains your finished article. You can:

  • Copy the content to your CMS, blog platform, or document editor.
  • Download the file from workspaces/my-blog/projects/<project-id>/final.md.
  • Iterate — if you want changes, edit an earlier artifact and re-run the affected stages using Execute Next or Retry Stage.

What’s Next