Skip to main content
The @mentions feature allows you to include external content in your prompts, similar to Cursor IDE’s mention system.

​
Quick Start

# Include a file
praisonai "@file:main.py explain this code"

# Include a doc
praisonai "@doc:project-overview help me understand this project"

# Search the web
praisonai "@web:python best practices give me tips"
Mentions Include Files in Prompts

​
Supported Mentions

MentionSyntaxDescription
File@file:path/to/file.pyInclude file content
Doc@doc:doc-nameInclude doc from .praison/docs/
Web@web:search querySearch the web
URL@url:https://...Fetch URL content
Rule@rule:rule-nameInclude specific rule

​
File Mention

Include file content in your prompt: 
praisonai "@file:src/main.py explain this code"
What happens:
  1. The file content is read
  2. Content is wrapped in a code block with language detection
  3. Content is prepended to your prompt
Example with multiple files: 
praisonai "@file:src/main.py @file:src/utils.py how do these files work together?"

​
Relative and Absolute Paths

# Relative path (from current directory)
praisonai "@file:src/main.py explain"

# Absolute path
praisonai "@file:/Users/me/project/main.py explain"

​
Doc Mention

Include documentation from .praison/docs/: 
praisonai "@doc:project-overview help me add a new feature"
Prerequisites:
  • Create docs using praisonai docs create
  • Or add markdown files to .praison/docs/
Example: 
# First create a doc
praisonai docs create coding-standards "Use type hints. Follow PEP 8."

# Then reference it
praisonai "@doc:coding-standards review my code"

​
Web Mention

Search the web and include results: 
praisonai "@web:python asyncio tutorial explain async/await"
What happens:
  1. Web search is performed using DuckDuckGo
  2. Top 3 results are included
  3. Results are prepended to your prompt
Requires duckduckgo-search package: pip install duckduckgo-search

​
URL Mention

Fetch and include content from a URL: 
praisonai "@url:https://docs.python.org/3/tutorial/index.html summarize this"
What happens:
  1. URL content is fetched
  2. HTML is converted to text
  3. Content is truncated if too long (max 10KB)

​
Rule Mention

Include a specific rule from .praison/rules/: 
praisonai "@rule:python-style apply these rules to my code"

​
Multiple Mentions

Combine multiple mentions in a single prompt: 
praisonai "@file:main.py @doc:coding-standards @web:python best practices review and improve this code"
Processing order:
  1. All mentions are extracted
  2. Content is fetched for each mention
  3. All content is prepended to the cleaned prompt
  4. Agent processes the combined context

​
Context Format

When mentions are processed, the context is formatted as: 
# File: main.py
```python
def hello():
    print("Hello, World!")

​
Doc: coding-standards

Use type hints for all functions. Follow PEP 8 style guide.

​
Web Search: python best practices

  1. “Python Best Practices” - realpython.com …

​
Task:

review and improve this code 

## Python API

```python
from praisonaiagents.tools.mentions import MentionsParser, process_mentions

# Initialize parser with default settings
parser = MentionsParser(workspace_path=".")

# Initialize with custom file size limit
parser = MentionsParser(
    workspace_path=".",
    max_file_chars=1000000  # 1 million chars
)

# Check if prompt has mentions
has_mentions = parser.has_mentions("@file:main.py explain")
print(has_mentions)  # True

# Extract mentions without processing
mentions = parser.extract_mentions("@file:main.py @doc:readme explain")
print(mentions)  # {'file': ['main.py'], 'doc': ['readme']}

# Process mentions and get context
context, cleaned_prompt = parser.process("@file:main.py explain this")
print(context)  # File content
print(cleaned_prompt)  # "explain this"

# Convenience function
context, prompt = process_mentions("@file:main.py explain")

​
Use Cases

​
Code Review

praisonai "@file:src/auth.py @doc:security-guidelines review this code for security issues"

​
Documentation

praisonai "@file:src/api.py generate API documentation for this file"

​
Learning

praisonai "@url:https://docs.python.org/3/library/asyncio.html explain async/await"

​
Research

praisonai "@web:machine learning trends 2024 summarize the latest developments"

​
Refactoring

praisonai "@file:old_code.py @doc:coding-standards refactor this code to follow our standards"

​
File Size Limits

By default, file content is limited to 500,000 characters (~125K tokens), which fits comfortably in modern LLMs like GPT-4o (128K), Claude 3.5 (200K), and Gemini (1M+).

​
Configuring the Limit

# Set custom limit (1 million characters)
export PRAISON_MAX_FILE_CHARS=1000000
praisonai "@file:large_file.py explain"

# Disable limit entirely
export PRAISON_MAX_FILE_CHARS=0
praisonai "@file:huge_file.py explain"

​
Limit Priority

  1. Constructor parameter - Highest priority
  2. Environment variable (PRAISON_MAX_FILE_CHARS)
  3. Default - 500,000 characters

​
Truncation Warning

When a file is truncated, a warning is logged: 
WARNING: File large_file.py truncated from 800,000 to 500,000 chars. 
Set PRAISON_MAX_FILE_CHARS=0 for no limit.
ModelContext WindowRecommended max_file_chars
GPT-4o128K tokens400,000 (default is fine)
Claude 3.5 Sonnet200K tokens600,000
Claude Sonnet 41M tokens3,000,000
Gemini 2.5 Pro1M tokens3,000,000
GPT-5400K tokens1,200,000
Token estimation: ~4 characters per token for English/code. Leave room for system prompt and output tokens.

​
Limitations

LimitationDetails
File sizeDefault 500KB, configurable via PRAISON_MAX_FILE_CHARS
URL contentMax 10KB after HTML stripping
Web searchTop 3 results only
Nested mentionsNot supported

​
Best Practices

Be Specific

Use specific file paths rather than directories

Combine Wisely

Don’t overload with too many mentions - context has limits

Create Docs

Create reusable docs for frequently needed context

Use Rules

Reference rules for consistent coding standards

​
Troubleshooting

IssueSolution
File not foundCheck the file path is correct and file exists
Doc not foundCreate the doc with praisonai docs create
Web search failedInstall duckduckgo-search package
URL fetch failedCheck URL is accessible and valid
  • Docs - Manage project documentation
  • Rules - Manage project rules
  • CLI Overview - PraisonAI CLI documentation