Submind: agent discipline + subconscious layer

A tiny Python toolkit that helps AI agents stop calling unfinished work "done".

It has two parts:

1. AgentDisciplineLayer — creates a completion contract, collects proof, detects lazy output, and blocks fake-done reports.
2. SubconsciousLayer — records successful agent trajectories and turns repeated actions into soft habits for future runs.

Use it with LangGraph, CrewAI, AutoGen, custom Python agents, or any async agent loop.

The bottleneck it solves

Agents often fail in boring ways:

• they give a plan instead of an artifact
• they say "done" without evidence
• they skip tests
• they stop after the first error
• they push verification back to the user
• they repeat weak habits across runs

Submind gives agents a simple work ethic:

Define done → collect evidence → verify checks → only then report complete

What is inside

agent_discipline.py

The practical anti-laziness layer.

It provides:

• CompletionContract
• Evidence
• FinishResult
• AgentDisciplineLayer
• lazy flag detection
• missing/failed done-check reports
• next-action guidance

subconscious_layer.py

The lightweight reflection layer.

It provides:

• trajectory reflection
• bounded JSON memory
• frequent successful action tracking
• safe markdown procedural memory
• soft priming data for future runs

Install

For now, copy these files into your project:

agent_discipline.py
subconscious_layer.py

Then import:

from agent_discipline import AgentDisciplineLayer
from subconscious_layer import SubconsciousLayer

Quick start: stop fake-done reports

from agent_discipline import AgentDisciplineLayer

layer = AgentDisciplineLayer()

contract = layer.create_contract(
    goal="Build a GitHub-ready Python package",
    done_checks=[
        "README exists",
        "tests pass",
        "example runs",
    ],
)

layer.add_evidence(contract, "README exists", path="README.md")
layer.add_evidence(contract, "tests pass", output="9 passed in 0.10s")

result = layer.can_finish(contract)

print(result.allowed)
print(result.report)
print(layer.next_action(contract))

Output:

False
Goal: Build a GitHub-ready Python package
Can finish: False
Missing: example runs
Collect evidence for: example runs

The agent cannot honestly say it is done until every check has passing evidence.

Detect lazy agent output

flags = layer.detect_laziness(
    message="Done. I created the project and it should work.",
    evidence=[],
    tool_calls_made=False,
)

print(flags)

Output:

[
  "claimed_done_without_evidence",
  "no_tool_calls",
  "vague_success_language"
]

Quick start: subconscious reflection

import asyncio
from subconscious_layer import SubconsciousLayer

async def main():
    memory = SubconsciousLayer(
        store_path="memory/subconscious_memory.json",
        procedural_path="memory/subconscious_procedures.md",
    )

    trajectory = [
        {"action": "research", "result": "found source"},
        {"action": "verify", "result": "checked result"},
        {"action": "write_file", "result": "saved safely"},
    ]

    await memory.reflect(trajectory, success=True)
    print(memory.prime("Need to complete a user task safely"))

asyncio.run(main())

Recommended agent integration

At the start of a task:

discipline = AgentDisciplineLayer()
contract = discipline.create_contract(
    goal=user_request,
    done_checks=["artifact created", "tests pass", "result verified"],
)

During the task:

discipline.add_evidence(contract, "tests pass", output=test_output)

Before final response:

result = discipline.can_finish(
    contract,
    final_message=draft_final_response,
    tool_calls_made=True,
)

if not result.allowed:
    raise RuntimeError(result.report)

After the run:

await subconscious.reflect(agent_trajectory, success=result.allowed)

Next run:

prime = subconscious.prime(current_context=user_request)

Inject prime as soft context only. Never let it override explicit user instructions.

Safety choices

• Does not overwrite your real soul.md
• Writes only inside a managed markdown block
• Keeps memory bounded with max_patterns
• Learns habits only from successful runs
• Treats habits as soft guidance, not commands
• Does not store secrets by design
• Blocks "done" unless proof exists

Output files from SubconsciousLayer

subconscious_memory.json

Stores raw patterns and distilled procedures.

subconscious_procedures.md

Stores a readable managed block:

<!-- BEGIN SUBCONSCIOUS LAYER -->
Updated: ...

## Implicit habits
- research (observed 2x in successful runs)

## Recommendations
- Research before making factual claims.
<!-- END SUBCONSCIOUS LAYER -->

If you point it at an existing markdown file, it preserves old content and updates only the managed block.

Tests

python3 -m pytest -q

Current verified result:

9 passed

Honest positioning

This is not magic memory.

It is a small discipline layer for agent work:

• the discipline layer prevents fake completion
• the subconscious layer remembers useful process habits

Together they help agents behave less lazy and more verifiable.