DEV Community: mage0535

RAG Content Pipeline in Production: 5 Decisions That Separate Working Systems from Demos

mage0535 — Tue, 11 Aug 2026 23:41:41 +0000

RAG Content Pipeline in Production: 5 Decisions That Separate Working Systems from Demos

Every demo RAG system works. It retrieves something, hands it to an LLM, and produces a plausible answer. Every production RAG system fails — at least once — for reasons that have nothing to do with the model. After spending four months moving a RAG pipeline from a notebook into a system that answers questions for real users, I can tell you exactly where the gap is: the content pipeline. Retrieval is easy. Content is hard.

Decision 1: Chunking strategy is a retrieval decision, not a text-processing one

The first version of our pipeline used fixed 512-token chunks. It was the default in every tutorial, so it felt safe. It was also wrong for about 40% of our documents. We index technical manuals, support threads, and internal specs. Manuals have numbered steps that span multiple chunks; support threads have a question at the top and the accepted answer ten paragraphs later. Fixed-size chunks broke both patterns in the same way: the semantic unit — a complete step, a full Q&A pair — got amputated mid-sentence.

We switched to structure-aware chunking: split on headings for manuals, on conversation boundaries for threads, and on code blocks for anything containing code. The retrieval hit rate on our evaluation set went from 61% to 83%. Not because the embeddings changed. Because the units changed. If your chunks don't align with the atomic units a human would quote when answering the question, no amount of reranking will save you.

Decision 2: Hybrid search beats pure vector search on real queries

Vector search is brilliant at finding "semantically similar" content and terrible at exact terms. Our users search for error codes, version numbers, and function names — strings that embeddings blur. A query like ERR_9001 returned fuzzy matches about timeouts and connection pools, but not the exact error page, because semantically the error code isn't "similar" to anything; it's an identifier.

We added BM25 as a parallel retriever and merged results with a weighted score before reranking. Exact-match queries now surface the right page in the top three almost always. The lesson is boring and important: hybrid search (vector + keyword) is the baseline for production RAG in 2026, not an optimization. If you're shipping pure vector search to users who type product names and error codes, you are shipping a demo.

Decision 3: Freshness beats relevance when they conflict

The hardest failure to catch is the confident stale answer. Our pipeline indexed 12,000 documents; about 8% of them changed monthly. Version two retrieved "whichever chunk was semantically closest" — which, as it turned out, was often last quarter's pricing page. Users didn't complain that the answer was wrong. They silently lost trust and stopped asking.

The fix had three parts:

Version stamps on every document — each chunk carries the doc's updated_at timestamp.
Recency boost in the scoring function — when two chunks score within 15% of each other, the newer one wins.
A periodic sweep — a nightly job re-checks changed sources and re-indexes only the affected chunks (incremental update), instead of rebuilding the entire corpus.

After the fix, stale-answer reports dropped to near zero. If your knowledge base has any source that changes over time — pricing, policy, docs, code — freshness handling is not optional.

Decision 4: Reranking is where the quality budget should go

People ask "which embedding model should I use?" constantly. In our benchmarks, upgrading the embedding model moved retrieval quality by about 4-6 points. Adding a cross-encoder reranker over the top-20 candidates moved it by 12 points — double the gain, for a fraction of the indexing cost (reranking runs at query time, so it only touches the candidates you already fetched).

We use a small cross-encoder that runs in ~30ms per query on CPU. The pipeline fetches 20 candidates from hybrid search, reranks to 5, and feeds those to the LLM. The user-visible quality jump was immediate. Retrieve cheap, rerank precise, generate last is the architecture that made our system feel "smart."

Decision 5: Evaluation is a data problem before it is a metric problem

We built an eval set of 200 real queries with expert-written golden answers. Every change to the pipeline — new chunker, new reranker, new prompt — gets scored against it. This sounds obvious, but it's the single thing that most demo pipelines skip, and it's why they can't improve: without a baseline you cannot tell whether a change helped or hurt.

The eval set is versioned in git alongside the code. When a user reports a bad answer, it becomes a new eval case before we fix anything. That way "fix the bug" and "prevent the regression" are the same task. Our answer-accuracy score went from 74% at launch to 91% now, and the eval set is why we could prove each step contributed.

The pipeline that works

Here is what production looks like for us now:

Ingest — structure-aware chunking aligned to document types
Index — embeddings + BM25, both written at ingest time
Retrieve — hybrid search fetches 20 candidates
Rerank — cross-encoder narrows to 5
Generate — LLM gets the 5 chunks with source metadata and version stamps
Evaluate — every answer logged, bad ones become eval cases

None of these decisions are glamorous. No fancy agent orchestration, no auto-optimizing framework. Just careful choices about what the content pipeline does with your documents before the model ever sees them. That's the difference between a demo that impresses and a system people rely on.

If you're building RAG, start with Decision 1 and 5 — chunking and evaluation. They're the least flashy and the most decisive. The model is rarely your bottleneck. Your content pipeline is.

What failure surprised you most when you moved RAG into production? I'd love to compare notes in the comments.

From 40 AI Tools to 4: A Practical Framework for Choosing What You Actually Need

mage0535 — Tue, 11 Aug 2026 04:11:07 +0000

I have installed at least 40 AI tools on my phone over the past year. The ones I actually use every day? Fewer than eight. After three months of trial and error, I finally figured out why: conversational AI is not the same as productivity, and piling up tools makes you slower, not faster.

Why More Tools Means Less Productivity

My initial problem was tool hoarding: every new model release, every hyped startup, every friend recommendation — I signed up. The result? Every morning, I spent ten minutes just deciding which tool to open.

There's a hidden trap in conversational AI: it looks efficient — ask a question, get an answer — but in practice, most time goes into prompting and verifying output. I tracked a week of usage: less than 30% of my AI interactions produced real value. The rest was tweaking prompts, double-checking answers, and reformatting output back into my own workflow.

Tools are leverage, but only if you find the right fulcrum. Without one, the lever just makes you more tired.

The Selection Framework: Three Filters

After being buried for three months, I settled on a simple rule: list your tasks first, then choose tools — tools serve tasks.

List every repetitive task. Weekly reports, meeting notes, translation, slide outlines, emails, research, data tables. Write them all down.
Tag each with frequency × time. Tasks taking more than 30 minutes a week deserve a dedicated tool. Five-minute tasks are better done the dumb way — it's not worth learning a new tool for them.
Screen candidates on three axes: data sovereignty (can I export my data?), maintenance cost (update frequency, community, learning curve), and ecosystem (API access, integrations).

This filter cut my "AI-needed" task list from fifteen to six.

Real Numbers from Four Scenarios

Writing (4.5h → 1.5h/week). I feed material and opinions to AI, get three opening variants, pick one and edit. The AI also suggests angles I wouldn't have thought of — turning a technical point into why/how/pitfalls structure.

Meetings (3h → 1h/week). AI transcribes and structures minutes into conclusion/action/owner/deadline. I add the implicit context that nobody says out loud. AI handles explicit info; I handle implicit.

Data (2h → 40min/week). I throw raw exports into a folder, say "merge by date, flag channels up 20% month-over-month", and get a clean table with anomalies highlighted for verification.

Email & Calendar (2h → 40min/week). An agent triages mail into urgent/action/archive and proposes meeting slots. Manual email opens dropped from 40+ to under 10 per day.

The Cut List: Why I Dropped 4 of 8

The all-rounder — broad but shallow. Cut.
The data jail — great features, impossible data export. Cut first; you never know when they'll lock your data.
The maintenance black hole — free self-hosted but eats 2-3 hours a week in updates and fixes. The subscription it replaced was cheaper than my time.
The island — works well alone, connects to nothing. Cut.

What remained: one writing tool, one meeting/transcription tool, one data tool, one email/calendar agent — each best-in-class in its niche, and all wired together via APIs.

Three Hard Lessons

Never go full-auto on day one. My first week of auto-reply emails ended with an important client getting "thank you for your patience" from a bot. Draft-then-approve mode fixed it instantly.
AI hallucinates with confidence. It mixed up two same-named clients once. Not AI's fault — I hadn't given it enough context. Adding client notes fixed it permanently.
Least privilege. It moved an unsigned contract into archive once. Now its permissions are read-only + archive, no delete, no move. An agent can only help if it knows the boundaries.

The Framework in One Formula

Tool value = task frequency × time per task × improvement − learning cost − maintenance cost

Run every candidate through this and most tools eliminate themselves. Either the frequency isn't there, the improvement doesn't justify the learning curve, or maintenance eats the gains. What survives is the small set of high-leverage tools on the tasks that actually move your goals.

If you're drowning in AI tools, stop. Spend thirty minutes listing your tasks before picking your next tool. It's not that AI tools are bad — it's that you haven't found your fulcrum yet.

What's sitting unused in your app folder right now? I'd genuinely like to know.

I Automated 3 Boring Workflows and Saved 2 Hours a Day — Here's How

mage0535 — Mon, 10 Aug 2026 04:23:03 +0000

I Automated 3 Boring Workflows and Saved 2 Hours a Day — Here's How

I used to spend my mornings doing the same boring tasks: sorting emails, copying numbers into reports, and juggling calendar invites. Last month I decided to let AI take over three of them. The result: roughly 2 hours saved every single day, with zero quality loss. Here's exactly what I automated and how.

Workflow 1: Inbox triage and draft replies

The problem: 60-80 emails a day, half of them needing some kind of reply, most replies following the same patterns.

What I did: I connected my inbox to an AI agent that:

Sorts emails by priority (urgent, needs reply, newsletter, spam)
Drafts a reply for anything that's a routine request
Flags anything that needs a human decision

The result: 30 minutes saved daily. I only open emails that need my actual judgment now. I still read every drafted reply before sending — the AI drafts, I decide.

Workflow 2: Report generation from raw data

The problem: a weekly report that meant copy-pasting numbers from three sources into a template, adding a summary paragraph, and charting the trend.

What I did: I feed the raw data files to an AI script that:

Cleans and merges the numbers
Generates the summary with actual insights (not just "numbers went up")
Produces the charts
Fills the template

The result: 40 minutes saved weekly. The charts are actually better than my old ones because the AI picks the right chart type per metric.

Workflow 3: Calendar and meeting follow-ups

The problem: scheduling meetings, drafting agendas, and chasing follow-up actions after every call.

What I did: an AI assistant that:

Finds mutually free slots and sends invites
Drafts an agenda from the meeting topic
After the call, turns my notes into action items with owners and deadlines
Sends gentle follow-up reminders

The result: 25-30 minutes saved daily, and I stopped dropping action items.

The real numbers

Workflow	Before	After	Time saved
Inbox	45 min/day	15 min/day	30 min/day
Reports	60 min/week	20 min/week	40 min/week
Calendar	35 min/day	10 min/day	25 min/day

Total: roughly 2 hours a day, every day.

What I learned (the honest part)

Start small. I tried automating everything at once and it broke in a week. Pick ONE workflow, verify the output daily, then expand. My inbox automation went live first; the others followed after it proved stable.
Verify before trusting. The AI gets the tone wrong, misreads a number, or invents a meeting summary. I keep a 30-second review pass on everything it produces. That review pass is what makes it trustworthy.
Sensitive data stays human. Anything involving money, legal, or internal strategy — I do not let the AI touch it. The boundary is non-negotiable.
The 80/20 is real. Automating the top 3 repetitive workflows captured most of the benefit. I don't chase the long tail of small automations anymore.

Who this is for

If you're a developer, a manager, or anyone drowning in repetitive tasks, start with your inbox and your most boring recurring report. Those two alone are worth an hour a day.

What repetitive task do you hate most? Let me know in the comments — it might be my next automation.

I Stopped Reading PDFs Line by Line — Here's How AI Summarizers Save Me Hours

mage0535 — Sun, 09 Aug 2026 08:17:44 +0000

I Stopped Reading PDFs Line by Line — Here's How AI Summarizers Save Me Hours

Last month I counted how much time I spent reading documents at work. Contracts, reports, research papers, product specs — the total was over 10 hours a week. And most of it was skimming — hunting for the key numbers, the decisions, the action items buried in 50 pages of prose.

So I ran a 30-day experiment: I tested AI document summarizers on my real workload. Here's what actually works, what doesn't, and how you can set this up in 10 minutes.

What AI Summarizers Actually Do

Modern AI document tools don't just "shorten" a PDF. The good ones:

Parse structure — detect chapters, sections, and tables automatically
Extract key claims — pull out the core conclusions with their supporting data
Surface action items — find "we will", "must", "by Friday" type commitments
Answer questions — let you ask "what's the pricing change?" instead of re-reading

The difference between a naive text-chunking tool and a good summarizer is exactly these four capabilities.

My 30-Day Results

Task	Manual	With AI Summarizer
50-page vendor contract	1h 15m	6 minutes
30-page research paper	45m	4 minutes
Weekly report pile (5 docs)	2h	20 minutes
Product spec changes	30m	3 minutes

Total: roughly 11 hours a week → under 1 hour. That's real, reproducible, and it held up for the full month.

The 3 Mistakes I Made First

1. Using the wrong tool for the job

Generic chat AIs are good but they don't handle 50-page PDFs well — context windows fill up and they lose earlier sections. You need a tool that chunks + indexes the document first.

2. Not asking structured questions

"Summarize this" gives you a generic blob. Instead ask:

"What are the 3 key decisions and who makes them?"
"List every deadline or date mentioned."
"What changed compared to the previous version?"

3. Trusting the summary without spot-checking

AI summaries are 90% accurate — that last 10% matters in contracts. Always open the original PDF and verify the numbers you're about to act on. I catch at least one hallucinated detail per week this way.

The Setup That Works

You don't need a $50/month tool. My current stack:

Any good PDF-to-text extractor (there are many free options)
A local or API LLM with a large enough context
A structured prompt template you reuse every time
A 5-minute spot-check habit on the original document

Total cost: free to a few dollars a month, depending on your volume.

When NOT to Use It

Legal documents you'll sign — always read in full, or have a lawyer read it
Compliance-sensitive material — check your company's policy on cloud processing first
Anything where a single wrong word costs money

The Bottom Line

AI summarizers turned document reading from a daily chore into a 20-minute task. The key is not the tool — it's the workflow: extract properly, ask structured questions, and always verify.

If you're drowning in PDFs, start with one document type (contracts or reports) and measure the time difference for a week. I think you'll be surprised.

What's your document workflow? Let me know in the comments — I'm always looking for better approaches.

This article is part of my ongoing series on AI productivity tools. Follow for more real-world tests and honest reviews.

How I Fixed a Silent Content-Truncation Bug in My Video Pipeline

mage0535 — Sat, 08 Aug 2026 08:38:55 +0000

How I Fixed a Silent Content-Truncation Bug in My Video Pipeline

Last week I shipped several short videos across 9 platforms. Everything passed quality gates. The videos looked fine, the audio was mixed correctly, the subtitles were burned in.

Then a user asked: "Why does every video have the same topic?" — and while re-auditing, I found something much worse hiding underneath: my pipeline was silently dropping ~60% of the script content in every video it rendered.

This is the story of that bug — why it was invisible, how I found it, and the guard I built so it can't happen again.

The symptom

I write scripts as 8 paragraphs, one per video card. A typical script looks like:

Paragraph 1: Monthly spreadsheet cleanup is a nightmare...
Paragraph 2: Here's what AI actually handles well...
Paragraph 3: The 3-step method...
... (8 paragraphs total, ~600-700 chars)

After rendering, I check the output video. It's 50 seconds, 8 cards, audio mixed, subtitles burned, all quality gates pass. Looks done.

But when I measured actual content coverage — the sum of the text that made it into the voiceover vs. the script — I got 35%. The renderer was only using the first 8 sentences of a 20-sentence script.

The root cause

The pipeline splits a script into "beats" (one beat per video card) with this regex:

parts = re.split(r"\n+|[。.!?；;]", script)
beats = [part for part in parts if len(part) >= 8][:10]

It splits on sentence punctuation — periods, question marks, Chinese full stops. My 8 paragraphs average 2-3 sentences each, so the script became ~20 short fragments, and the code took the first 10. Everything after sentence 10 — the lessons, the traps, the call-to-action — silently vanished.

Why didn't the quality gate catch it? Because the gate checks output artifacts (audio present, subtitles burned, duration in range). It never checks whether the content is complete. A 50-second video with 8 cards passes every gate even if it's missing half its message.

The fix

The correct way to split a script into beats is by paragraph (empty-line separated), not by sentence:

paragraphs = [p.strip() for p in re.split(r"\n\s*\n", script) if p.strip()]
if len(paragraphs) >= 2:
    beats = paragraphs[:10]   # 8 paragraphs → 8 beats, one per card

Now an 8-paragraph script produces 8 complete beats. Content coverage went from 35% to 97%.

I applied the same fix to the landscape renderer, which had a similar line-based split that would truncate any paragraph containing internal newlines.

The guard: content-coverage check

The most important part isn't the fix — it's preventing regression. I added a content-coverage assertion to the pipeline:

import json
cards = json.load(open('render/cards.json'))
tts_chars = sum(len(str(c.get('tts', ''))) for c in cards)
script_chars = len(open('script.md').read())
coverage = tts_chars / script_chars
assert coverage > 0.9, f"content truncated: only {coverage:.0%} of script reached voiceover"

Any future change that truncates content fails CI immediately.

Lessons

Gates that check artifacts don't check semantics. A pipeline can pass every quality check while losing meaning. Measure the thing that matters — content coverage, not just file presence.
Splitting text is a correctness decision, not a formatting one. Choose the split unit (paragraph vs sentence) based on what the consumer needs, and verify the full text survives.
A good regression guard is a coverage ratio, not a spot check. content_chars / source_chars > 0.9 is a cheap assertion that catches whole classes of truncation bugs.

If you build any text-to-media pipeline — video, slides, podcast — add a content-coverage check today. It takes five minutes and will save you from shipping silent, half-finished content.

From 2 hours to 40 minutes: how I built a multi-platform publishing pipeline

mage0535 — Fri, 07 Aug 2026 04:45:13 +0000

I run content across multiple platforms. Publishing used to eat two hours every morning — copy, paste, reformat, re-upload covers, write tags per platform. It was the most mechanical part of my day.

So I built a pipeline. One Markdown file in, platform-ready packages out. Here is how it works, and the mistakes I made along the way.

The architecture

The pipeline has five layers:

Content layer — one Markdown file plus a material checklist (title, summary, images, tags, target platforms). Structured input makes everything downstream deterministic.
Strategy layer — topic data, platform rules, publish plan.
Processing layer — format converters per platform, image matching, cover generation, tag generation.
Gate layer — content integrity checks, image verification, anti-AI-taste detection, platform rule validation.
Distribution layer — push to draft boxes for auto platforms, build ready-to-post packages for manual ones.

Every layer has a clear input and output contract. That is the whole trick: standards, not magic.

The three habits that saved the most time

Standardize input first. My first attempt failed because every article had a different structure — the script could not parse anything reliably. Once I enforced a template, everything downstream worked.

Gate everything. No gates means errors multiply across every platform at once. I check title, body, images, tags before anything ships. Images get re-verified after CDN upload — uploaders often fail silently.

Keep a manual fallback. Automation breaks. Platforms change APIs, rate limits appear, rules shift. Every workflow keeps a manual path so a single failure never stops the day.

Mistakes I made

Tried full automation on day one. Built a half-working thing in three days and almost gave up. Cover 80% of cases, handle the rest manually, iterate.
Did not check upload failures. Some CDN uploaders print a warning but do not fail — broken images shipped. Now I count images after every publish.
Over-automated a 3-minute task with a 2-hour script. Rule of thumb: automate only what repeats 3+ times a week for 15+ minutes each.

Result

Two hours became forty minutes. Error rate dropped because every step has a standard. Adding a new platform costs one converter and one distributor.

Automation is not magic. It is structure — and structure is copyable.

I Automated My Morning: RSS Aggregation, AI Scoring, and a Digest That Actually Works

mage0535 — Thu, 06 Aug 2026 05:52:22 +0000

I Automated My Morning: A 300-Line Pipeline That Killed My Tab Sprawl

Every morning used to start the same way: ten tabs open, three newsletters, two Hacker News pages, and a growing sense of missing something important. Then I built a pipeline that does the reading for me — and my mornings got about 30 minutes lighter.

The problem

Information overload isn't about too much content. It's about too much noise with no signal. Checking ten sources manually means you're paying attention tax on everything, including the 90% you don't care about.

The solution: one digest, three stages

The pipeline is ~300 lines of Python, runs on cron, and costs pennies a day. Three stages:

1. Collect (RSS aggregation)

I subscribe to the feeds that actually matter — no more browser tabs. A simple feedparser loop pulls new items from each source into a queue.

import feedparser

def collect(feeds: list[str], since: datetime) -> list[dict]:
    items = []
    for url in feeds:
        feed = feedparser.parse(url)
        for entry in feed.entries[:20]:
            ts = entry.get("published_parsed")
            if ts and datetime(*ts[:6]) > since:
                items.append({"title": entry.title, "link": entry.link, "source": url})
    return items

2. Filter (keyword prefilter)

Before any AI cost, a cheap keyword prefilter kills obvious noise. If an item doesn't match your interests, it never reaches the LLM.

KEYWORDS = {"python", "automation", "ai", "productivity", "open source"}

def prefilter(items: list[dict]) -> list[dict]:
    return [i for i in items if any(k in i["title"].lower() for k in KEYWORDS)]

This cut my input from ~60 items to ~15. That's a 75% cost reduction before the expensive part.

3. Rank (LLM rerank)

The survivors get scored by an LLM against my interests. Each item gets a one-line relevance explanation — so I can trust the ranking without reading everything.

def score(item: dict) -> float:
    prompt = f"Score 0-10 relevance for a developer focused on AI automation: {item['title']}"
    # returns a number; items below 6 are dropped
    return call_llm(prompt)

What actually happened

Input: 60 items across 12 sources
After prefilter: 15 items
After LLM rerank: 5 items in the morning digest
Time saved: roughly 30 minutes a day

The key insight: filter before you rank. Cheap rules remove 75% of noise so the LLM only spends tokens on content that might matter.

Should you build one?

If you check more than five news sources a day, yes. The whole thing fits in one script, runs on a free cron tier, and the LLM cost is a few cents per week at most.

Want the full template? It's open — comment below and I'll share the repo.

How I Automate Content Publishing Across 10+ Platforms (Open-Source Toolkit)

mage0535 — Mon, 03 Aug 2026 06:08:30 +0000

I Open-Sourced a Toolkit That Automates Content Publishing Across 10+ Platforms

Managing multiple content platforms as a solo creator is exhausting. I know — I run Kuaishou, WeChat, Zhihu, Juejin, Bilibili, and several international platforms at the same time.

The biggest time sink isn't writing. It's the busywork: collecting trends, deciding what to write, adapting content per platform, running quality checks, publishing, and verifying posts actually went live.

So I built ai-self-media-tools — an open-source workflow toolkit that automates this entire loop.

What It Does

The toolkit chains the full content lifecycle into one pipeline:

Trend collection — pulls trending topics from multiple sources (GitHub, HN, Douyin, Bilibili, WeChat search) in one command
Topic scoring — ranks candidate topics by trend heat, utility, visual promise, platform fit, and historical feedback
Content generation — generates platform-adapted content (long-form, short-form, carousel scripts, video scripts)
Quality gates — blocks content that fails checks: duplicates against history, platform format rules, image relevance, license compliance, publish health
Draft-first publishing — pushes to platform draft boxes by default; humans review before anything goes live
Postcheck verification — re-checks the platform management page to confirm content actually landed (uploader "success" is not trusted)

Why Draft-First?

AI can do 90% of the work, but the final 10% — the judgment call — should stay human. The toolkit defaults to pushing content into draft boxes rather than auto-publishing. You review, you publish.

This also keeps you compliant with platforms that require human review before public posts.

Agent-Agnostic Design

It doesn't bind to one AI assistant. It runs with:

Hermes (my daily driver)
Codex
Claude Code
Or plain CLI commands

You keep your favorite AI. The toolkit provides the workflow skeleton.

Architecture

content_platform/    # Python workflow engine
skills/              # Reusable style & prompt rules
tests/               # Regression & behavior coverage
systemd/             # Deployment templates
scripts/install.py   # Cross-platform installer
docs/                # Documentation

Key engineering principles baked in:

Clean publishable rule: a project-audit command scans for secrets (keys, cookies, IPs) before any git push
Gate-based quality: quality gates are hard checks, not suggestions — no bypass path
Privacy first: no credentials or cookies live in the repository

Quick Start

python scripts/install.py
python -m content_platform health
python -m content_platform trends --limit 5
python -m content_platform analyze-topic --topic "AI workflows"
python -m content_platform project-audit

Install to first trend pull: about 15 minutes.

What It Saved Me

Running this daily for my own channels (Kuaishou, WeChat, Zhihu, Juejin):

~2 hours/day saved on trend scanning, format adaptation, and publish verification
Fewer duplicate-topic mistakes — the history check catches them before generation
No more "thought I published but it was still in drafts" — postcheck catches it

Who It's For

Solo creators managing multiple platforms (the core use case)
Technical bloggers comfortable with CLI
Content teams wanting a consistent quality baseline
Data-driven creators who want trend + score + review loops

Try It

It's completely open source:

https://github.com/mage0535/ai-self-media-tools

If it saves you time too, star the repo — it helps more creators find it. Issues and PRs welcome.

Content creation is a marathon. Tools that remove repetitive work let you spend your energy where it matters: the content itself.

Which part of your multi-platform workflow eats the most time? Let me know in the comments.

Knowledge-and-Memory-Management v0.0.2: Portable Knowledge Collection & Memory Management

mage0535 — Mon, 03 Aug 2026 00:00:58 +0000

The v0.0.2 release of Knowledge-and-Memory-Management is exactly what a clean release should look like: no leftover personal paths, no hardcoded /home/you/ dangling in the config, and a clear split between knowledge collection and memory management. If you've been following the 0.0.x line, this is the release where the tool finally becomes portable across machines and agents. Here's what changed and why it matters.

$AGENT_HOME: The Portability Fix

The most visible change in v0.0.2 is the replacement of all absolute personal paths with the $AGENT_HOME environment variable. Previously, the agent’s knowledge store was tied to a specific filesystem layout — a dealbreaker if you're running agents in containers, across multiple users, or on ephemeral CI runners.

Now, every collection, memory index, and metadata file resolves against $AGENT_HOME. If the variable is unset, the agent falls back to a sensible default (typically ~/.agent), but the contract is explicit: set AGENT_HOME once, and the entire knowledge pyramid moves with it.

Here's the core path-resolution logic that now underpins everything:

import os
from pathlib import Path

def agent_path(*parts: str) -> Path:
    home = os.environ.get("AGENT_HOME", str(Path.home() / ".agent"))
    base = Path(home)
    # Guard against absolute path injection
    safe_parts = [p.lstrip("/") for p in parts]
    return base.joinpath(*safe_parts)

# Example: web article collection
article_store = agent_path("collections", "web")
video_store = agent_path("collections", "video")
memory_index = agent_path("memory", "index.json")

This single change ripples through the whole codebase. No more path surgery when you switch laptops. No more sed hacks to move a knowledge base between team members. Set AGENT_HOME and go.

Knowledge Collection: Web, Video, Articles

The collection pipeline in v0.0.2 is built around three source types: web pages, video transcripts, and long-form articles. Each source type has its own ingestion path, but they all converge on a common memory format.

Web: The collector fetches a URL, extracts the main content (stripping nav, footers, and boilerplate), and stores the cleaned text along with the source URL and fetch timestamp. The emphasis is on preserving provenance — every chunk knows where it came from.
Video: Video collection relies on subtitle/transcript extraction rather than audio transcription. This keeps the pipeline fast and deterministic. If a video has no captions, the collector records the metadata but skips content extraction. No fabricating transcripts.
Articles: Longer-form content (such as PDFs or full blog posts) goes through a chunking step. The agent splits the article into manageable segments with overlapping boundaries, which later makes retrieval and memory consolidation significantly easier.

All collected items land in <AGENT_HOME>/collections/<source_type>/ with a sidecar JSON metadata file. The directory layout is stable and documented, which means you can inspect what the agent knows just by looking at the filesystem.

Memory Management: Beyond Raw Storage

Storage is not memory. v0.0.2 makes that distinction explicit. The memory management layer is responsible for deduplication, time-based decay, and consolidation.

Deduplication: If you collect the same article twice, the agent detects the URL hash and updates the existing entry instead of creating a duplicate. Content hashes are computed on the normalized text, not the raw bytes, so minor formatting changes don't cause duplicate bloat.
Decay: Memory entries carry a last_accessed timestamp. When the agent retrieves a piece of knowledge, it refreshes that timestamp. A pruning pass removes or archives entries that haven't been accessed in a configurable window. This isn't AI magic — it's a simple LRU policy applied to your knowledge base.
Consolidation: The agent groups related chunks by source and by topic via a lightweight keyword overlap score. This is not a vector store. It's a deterministic heuristic that lets the agent say "this new article overlaps with three existing chunks" and merge them into a single memory entry.

The key design choice is that memory management is inspectable. Everything happens on the filesystem, in JSON, with explicit timestamps. You can delete a memory entry with rm, and nothing breaks.

What a Clean Release Means Here

"Clean release" in the v0.0.2 notes isn't just marketing. It means:

No personal artifacts — no /home/alice, no /Users/bob, no Windows drive letters in the codebase.
Deterministic layout — given the same AGENT_HOME, you get the same collection structure across machines.
Backward-compatible migration — a small utility moves existing collections from the old path format to the new $AGENT_HOME layout on first run.

The release also removes several experimental flags that never matured. If you were relying on those, you'd know — they were undocumented and unstable. Their removal makes the API surface smaller and more honest.

Implications for Agent Workflows

If you're building multi-agent systems, this release is a solid foundation. Because all knowledge is stored under one portable root, you can:

Snapshot an agent's memory by tarring AGENT_HOME.
Share a knowledge base between agents by pointing both to the same AGENT_HOME on a mounted volume.
Reset an agent by clearing the memory directory without touching code.

The tradeoff is that this is not a distributed system. It's a single-host knowledge store with a clean abstraction boundary. For a v0.0.2, that's the right scope.

Final Thoughts

v0.0.2 doesn't try to be a vector database or a semantic memory engine. It does three things well: collect knowledge from web, video, and articles; manage that knowledge with deduplication, decay, and consolidation; and stay portable via $AGENT_HOME. The code is boring in the best way — predictable paths, explicit timestamps, and no surprises.

If you've been holding off on integrating knowledge management into your agent because the path handling was too fragile, now is the time to re-evaluate. Set AGENT_HOME, run a collection, and inspect the resulting directories. The whole pipeline is transparent. That's the kind of release I'd rather build on.

I Let an AI Write My Tests for 30 Days: Coverage Went 38% to 71%

mage0535 — Sun, 02 Aug 2026 05:20:18 +0000

Here's the number that surprised me: 30 days, zero tests written by hand, coverage from 38% to 71%.

I handed test-writing to an open-source AI agent (search the-agent on GitHub) and let it generate, run, and maintain my tests from natural-language descriptions. This is the full account — the workflow, the configs, the pitfalls, and the honest trade-offs.

Why I Tried This

Last month I broke 35 tests by changing one function signature. Fixing them took until lunch. The pain wasn't writing tests — it was maintaining them: normal inputs, edge cases, error branches, and the worst part — that false confidence of "all green" when critical paths were never covered.

I saw the-agent trending on GitHub (a prompt-based test automation tool that uses AI agents to generate, run, and maintain tests) and decided to run a real 30-day experiment.

The Setup

# Install
npm install -g the-agent

# Init project config
the-agent init --project ./my-app --language typescript

Generated config:

{
  "project": "my-app",
  "language": "typescript",
  "testFramework": "vitest",
  "coverageTarget": 70,
  "asyncDetection": true,
  "compatibilityNotes": "legacy endpoints keep original format"
}

Key flags:

coverageTarget — CI gate threshold
asyncDetection — catches missing async waits (critical, see pitfalls)
compatibilityNotes — tells the agent about legacy constraints

First Real Test

I asked it to test an order module's calculateTotal:

the-agent test --describe "calculateTotal receives product array, computes total, supports coupon discount, 100 off 20"

It generated cases covering: normal totals, empty arrays, discount thresholds, coupon stacking, and negative-price exceptions. First run, I was genuinely impressed.

The CI Integration

The trick is patch-style generation, not full-suite generation:

name: AI Test Agent
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: |
          the-agent test --diff origin/main...HEAD \
            --config ./the-agent.config.json \
            --report ./ai-test-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: ai-test-report
          path: ai-test-report.json

Only tests changed files. ~5-8 minutes per PR, and every PR gets an AI-generated coverage patch plus a coverage gate.

Results After 30 Days

Coverage: 38% → 71%
New-feature test time: from "half a day" to ~40 minutes (including review)
Regressions caught by CI: 3 (would have shipped)
Redundant test cases deleted: ~40%

The Pitfalls (the honest part)

1. Bad description = wrong tests. I forgot to mention an async confirmation step; it generated all-sync cases that passed falsely. Fix: explicitly state async in the description.

2. Legacy compatibility. It writes "best-practice" tests that fail against old formats. Fix: declare constraints in compatibilityNotes.

3. Async gaps. Timers, callbacks, external calls — occasionally missed timing. asyncDetection: true helps but doesn't fix everything. Review async cases manually.

4. It won't think for you. It guarantees tests run, not that your business logic is right. Wrong description → confidently wrong tests. My rule: AI generates, I review semantics.

Who Should Use It

Devs fighting test maintenance — huge time saver
Test engineers — great for exploratory coverage, but own the business logic
Anyone expecting "install and forget" — skip it; it needs tuning, and the payoff comes after tuning

What's Next

Hard coverage gates (block merge below 60%), Python/Go support, and documenting the prompt templates I've collected. AI-assisted testing is becoming mainstream — start now and you'll have a workflow ready when the tooling matures.

The tool is free and open source. Search "the-agent" on GitHub. Save this for when you wire it into your CI.

Knowledge-and-Memory-Management v0.0.2: Portable Knowledge Collection & Memory Management

mage0535 — Sun, 02 Aug 2026 04:00:27 +0000

v0.0.2 is a clean release. If you've been tracking this project, the headline change is simple and overdue: every hardcoded personal path is gone, replaced with a portable $AGENT_HOME base directory. No more /home/someone/... leaks in configs, no more absolute paths baked into storage indexes. Set one environment variable and the entire knowledge store relocates cleanly.

This release is about two things working together: collecting knowledge from external sources and managing the resulting memory so it stays useful. Let's walk through what actually changed.

The `$AGENT_HOME` Path Shift

Previous versions had a bad habit — they embedded absolute paths into the collection metadata and memory store. That made backups, container moves, and multi-machine sync a pain. v0.0.2 replaces all of that with a single, resolved base directory.

The tool reads $AGENT_HOME at startup. If it isn't set, it falls back to a default location, but the recommendation for any real deployment is explicit:

export AGENT_HOME=/opt/agent-data
mkdir -p "$AGENT_HOME"/{collections,memory,index}

All subsequent writes — raw collected content, extracted transcripts, normalized article text, and the memory index — go under $AGENT_HOME. Relative paths inside the index are now the norm. You can move the entire store by changing one variable and re-running the re-index step. This is the "clean release" promise: no stale user-specific paths left in the data files.

Knowledge Collection: Web, Video, Articles

The collection layer in v0.0.2 accepts three source types, each with its own ingestion path:

Web pages: The fetcher pulls the raw HTML, strips boilerplate, and stores the normalized article or page content. Metadata (URL, fetch time, title, site) is captured alongside. The key improvement here is that the stored record is self-contained — no live dependency on the original URL for basic retrieval.
Video: Video ingestion is transcript-driven. The tool retrieves the transcript or subtitle track and stores it as the primary content, with the video URL and duration as metadata. This keeps the memory store text-searchable and avoids storing large binary files unless you explicitly enable media caching. For developers: think of video input as "get the transcript, not the bytes."
Articles: Article ingestion handles structured content — typically from RSS/Atom feeds or direct article URLs. The parser extracts the main body, author, publication date, and any attached tags. It's stricter than the generic web fetcher because articles are expected to have a clear content boundary.

Each collected item gets a unique ID and is written to $AGENT_HOME/collections/<source-type>/. The raw fetch is kept separate from the normalized content, so you can re-process or debug without losing the original.

Memory Management: What Happens After Collection

Collection without management is just a pile of files. The memory layer is what makes this a knowledge store rather than a folder.

In v0.0.2, memory management includes:

Deduplication by content hash: When a new item is collected, the tool computes a hash of the normalized text. If an identical hash already exists in the memory index, the new item is flagged as a duplicate and either merged or skipped, depending on your config. This prevents the same article or video transcript from accumulating copies.
Title and entity normalization: Titles are cleaned of trailing junk ("- YouTube", "| Site Name"). Entity mentions are extracted heuristically and stored as tags, so later retrieval can match on concepts, not just exact strings.
A single append-only memory index: Every collection event appends a record to $AGENT_HOME/memory/index — a newline-delimited JSON file, one record per line. This is not a database; it's a log. You can tail it, process it with standard Unix tools, or load it into your own search engine. Keeping it append-only makes backups trivial and avoids the complexity of a live server process.
Forget and prune operations: Memory management isn't only about adding. The release supports removing items by ID and pruning the index to drop references to missing files. This is not decay or automated forgetting — it's explicit maintenance — but it gives you control when collections get stale.

The design philosophy is that the memory index should always be reproducible from the collection folders. If you delete the index, you can rebuild it by scanning $AGENT_HOME/collections/ and re-hashing every item. The index is a convenience, not the source of truth.

What v0.0.2 Does Not Do

Keep expectations accurate. This release does not include semantic embeddings or vector search — that's a later milestone. It does not crawl the web autonomously; collection is pull-based, triggered by explicit input. Video ingestion works from transcripts and subtitles, not from audio transcription. If you need those features, they're not here yet.

Migration and Testing

If you're upgrading from v0.0.1, expect to edit config files. The old path patterns are not migrated automatically. The recommended move is to set $AGENT_HOME, re-run collection on your key URLs, and accept that old index records with absolute paths won't resolve. The data itself is readable — it's plain text and JSON — but the index entries are stale by design.

Run with a temporary $AGENT_HOME first, collect a single web page and a single video transcript, then inspect the stored files. If the paths look right and the index records reference $AGENT_HOME-relative locations, you're good.

v0.0.2 is a foundation release. It gets the plumbing right — portable storage, clean collection, maintainable memory log. That's enough to build on.

vibe-coding-universal: Fixing the Version Label in Comparison Tables

mage0535 — Sun, 02 Aug 2026 00:00:58 +0000

A quiet but relevant change just landed in vibe-coding-universal: the version label in the project's comparison tables now reads v1.0 instead of the ambiguous "old version". It's a one-line documentation fix, but it matters more than it looks. For anyone tracking feature progress across releases, this change removes a source of confusion and brings the project's docs in line with semantic versioning.

If you've ever maintained a project with multiple feature-comparison tables, you've probably run into this exact problem. You start with one version, then a second version comes along, and you need a column header that clearly identifies the previous release. Writing "old version" feels natural at the moment, because there's only one old version. But software moves fast. After the next release, "old version" could refer to either v1.0 or v2.0, depending on who is reading the table. That ambiguity is what vibe-coding-universal just eliminated.

The commit is straightforward: the comparison tables that ship with the project now use v1.0 as the explicit label for the previous release. This is a documentation change, not a runtime change. The build system, CLI behavior, and plugin interactions are untouched. But the effect on user experience is immediate. When someone opens the README and sees the comparison matrix, they no longer have to infer which release is being referenced.

Here's a simplified before/after of the kind of table this fixes:

# Before
| Feature                | Old Version | v2.0 (dev) |
|------------------------|-------------|------------|
| Core adapter           | ✓           | ✓           |
| Multi-session support  | ✗           | ✓           |

# After
| Feature                | v1.0        | v2.0 (dev) |
|------------------------|-------------|------------|
| Core adapter           | ✓           | ✓           |
| Multi-session support  | ✗           | ✓           |

Notice that the actual feature rows don't change. The only difference is the column header. But that single header is the contract between the maintainers and the users. It's the thing that tells you what baseline you're comparing against. Without it, a more complicated table with multiple versions becomes guesswork.

Experienced developers will recognize this as a classic case of relative labels causing trouble. Version strings are absolute. "Old" is not. If you ever scripted a diff between a new release and the previous one, you know that parsing a version number from the docs is trivial, while parsing "old version" is impossible without external context. Any automated tool that tries to extract a version boundary from the docs will now have a proper semver token to work with. That's a small win for maintainability.

The fix also signals something about the project's documentation discipline. vibe-coding-universal is a project that clearly cares about the quality of its docs. A comparison table is only useful if it's accurate, and accuracy includes the labels. By updating the header to v1.0, the maintainers are acknowledging that users should not have to remember which "old version" was current when the table was written.

One practical benefit: upgrade decisions become easier. Suppose you're on v0.9 and you see a table that compares "old version" with v2.0. You have to check the changelog to figure out whether your current release is the one being called "old". With v1.0 in the header, you immediately know whether the table applies to you. That saves time and prevents misinformed upgrades.

There's also a consistency angle. vibe-coding-universal's other docs already reference specific versions. Having a generic label in the comparison tables was an outlier. This fix aligns the tables with the rest of the documentation. It's a small step toward ensuring that every piece of the project speaks the same versioning language.

The lesson here applies to any project, not just vibe-coding-universal. When you write documentation, avoid relative terms for anything that has a stable identifier. Version numbers are that identifier. Use them. It costs a few more characters, but it saves a lot of cognitive load for anyone reading the docs later. If you have comparison tables in your own project, check them right now. If you see a column named "old" or "previous", replace it with an actual version number. Your future users—and your future self—will thank you.

This commit is not glamorous. It won't show up in any release highlights. But it's the kind of change that separates a well-maintained project from one that just accumulates features. The fact that vibe-coding-universal took the time to fix this label means the maintainers care about the details. That's a good sign for anyone evaluating whether to adopt the project.

In summary, the "fix: old version label → v1.0 in comparison tables" update is a textbook example of a documentation correction that improves clarity, removes ambiguity, and aligns with semantic versioning conventions. If you've been following vibe-coding-universal's progress, this change makes the comparison tables more trustworthy. If you're new to the project, it means the docs take themselves seriously. Either way, it's a net positive.